sqs_transport 1.0.0

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2008 Ben Koski
+
+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,24 @@
+= sqs_transport
+
+== OVERVIEW
+
+sqs_transport is a wrapper around RightScale's excellent {RightAws::SqsGen2 library}[http://rightscale.rubyforge.org/right_aws_gem_doc/]
+to facilitate simple queue and receive operations.
+
+sqs_transport has four major components:
+
+* SQS::Config, a class to hold AWS credentials.  You'll need to define credential values for queueing to actually work.
+* SQS::Queue, a class to easily create RightAws::SqsGen2 instances, given a queue name
+* SQS::Message, a class allowing arbitrary contents (strings, hashes, arrays) to be queued and dequeued from SQS
+* SQS::Transport, a mixin to quickly add <tt>queue!</tt>, <tt>dequeue!</tt>, and <tt>receive!</tt> methods to push class data through SQS.
+
+See class docs for specific examples.
+
+== LINKS
+
+* Source code: http://github.com/bkoski/sqs_transport
+* Documentation: http://sqs-transport.rubyforge.org
+
+== AUTHOR
+
+Ben Koski, http://github.com/bkoski, ben.koski (at) gmail.com

data/lib/sqs/config.rb

@@ -0,0 +1,32 @@
+require 'facets'
+
+
+module SQS
+
+# SQS::Config stores your AWS access_key and secret_access_key.  These attributes raise exceptions
+# if they are checked but have not been set.
+  class Config
+    
+    @@access_key = nil
+    @@secret_access_key = nil
+    
+    cattr_writer :access_key, :secret_access_key
+
+    def self.access_key
+      raise ArgumentError, "No access key defined!" if @@access_key.nil?
+      return @@access_key
+    end
+    
+    def self.secret_access_key
+      raise ArgumentError, "No secret access key defined!" if @@secret_access_key.nil?
+      return @@secret_access_key
+    end
+    
+    # Load configuration from a YAML::load-generated hash
+    def self.parse yaml_hash
+      self.access_key = yaml_hash['access_key'] unless yaml_hash['access_key'].nil? || yaml_hash['access_key'].empty?
+      self.secret_access_key = yaml_hash['secret_access_key'] unless yaml_hash['secret_access_key'].nil? || yaml_hash['secret_access_key'].empty?
+    end
+    
+  end
+end

data/lib/sqs/message.rb

@@ -0,0 +1,132 @@
+module SQS
+
+  # SQS::Message provides a light wrapper over the RightAWS SQS API. It embeds the message payload
+  # in a JSON container to allow enqueue time and time_in_queue calculations.
+  #
+  # Note that by default, JSON serialization is used to encode <tt>contents</tt>. This means that
+  # <tt>contents</tt> must be JSON-serializable (i.e. no cyclical objects, singleton strings, etc.)
+  # If this is problematic, the serialization mechanism can be customized by overriding the <tt>serialize</tt>
+  # and <tt>self.deserialize</tt> methods.
+  #
+  # To use, simply instantiate, set the <tt>contents</tt> and call queue!
+  # For example:
+  #
+  #  m = SQS::Message.new 'my_test_queue'
+  #  m.contents = {:var1 => 1, :var2 => 2}
+  #  m.queue!
+  #
+  # pushes a message containing {:var1 => 1, :var2 => 2} to the 'my_test_queue' queue on SQS
+  #
+  # To retrieve the message, simply call:
+  #  m = SQS::Message.receive 'my_test_queue'
+  # 
+  # You can then inspect the contents
+  #  m.contents # returns {'var1' => 1, 'var2' => 2 }
+  # remove from the SQS queue
+  #  m.dequeue!
+  # or check the time in queue
+  #  m.time_in_queue
+  # You can also retrieve the SQS id for the message with the <tt>id</tt> method.
+  #
+  class Message
+  
+    # The raw RightAws message retrieved from SQS
+    attr_accessor :raw_message
+  
+    # Payload to be sent across the wire
+    attr_accessor :contents
+  
+    attr_accessor :enqueued_at, :received_at, :queue_name
+  
+    # Retrieves one or more Message objects from an SQS queue
+    # * <tt>queue_name</tt> is the name of the SQS queue
+    # * <tt>number_to_receive</tt> sets the maximum number of messages to return. If set to 1, a single instance is returned; if > 1 an array is returned. Defaults to 1.
+    #
+    # Valid options:
+    # * <tt>:visiblity</tt> - sets the visiblity timeout on the message in seconds
+    def self.receive queue_name, number_to_receive=1, opts={}
+      messages = SQS::Queue[queue_name].receive_messages(number_to_receive, opts[:visibility])
+      received_at = Time.now.utc
+      messages.map! { |m| self.create_from_raw_message(queue_name, m, received_at) } 
+    
+      number_to_receive == 1 ? messages.first : messages
+    end
+  
+    # Retrives one or more messages from the queue, but sets their visiblity to zero so that
+    # they can immediately be picked up by another worker. Useful for previewing messages on the queue.
+    # * <tt>queue_name</tt> is the name of the SQS queue
+    # * <tt>number_to_view</tt> sets the maximum number of messages to return. If set to 1, a single instance is returned; if > 1 an array is returned. Defaults to 1.
+    # No options at this time.
+    def self.peek queue_name, number_to_view=1, opts={}
+      self.receive(queue_name, number_to_view, :visibility => 0)
+    end
+  
+    # Initialize with the name of the name of the SQS queue. When queue! is called on an instance,
+    # data will be pushed to this queue.
+    def initialize new_queue_name
+      @queue_name = new_queue_name
+    end
+  
+    # Returns the SQS id for this message; nil if the message has not yet been queued.
+    def id
+      raw_message ? raw_message.id : nil
+    end
+  
+    # Serializes <tt>contents</tt> and pushes data onto the SQS queue.
+    def queue!
+      @enqueued_at = Time.now.utc
+      raise SQS::MessageSizeError, "Message exceeds 8k limit by #{sqs_message_body.size - 8_000} bytes" if sqs_message_body.size > 8_000
+      raw_message = SQS::Queue[queue_name].push(sqs_message_body)
+    end
+  
+    # Call after retrieving to delete the message from SQS so that it cannot be retrieved by another client.
+    def dequeue!
+      raw_message.delete
+    end
+  
+    # Returns time message spent on queue in seconds.
+    # Raises an ArgumentError if called on a message that has not been dequeued.
+    def time_in_queue
+      raise ArgumentError, "This message has not been dequeued properly; either enqueued_at or received_at is nil" if enqueued_at.nil? || received_at.nil?
+      enqueued_at - received_at
+    end
+  
+    # Given an object, serialize it to a string. By default, this simply calls to_json
+    # on the object, but could be overriden to serialize using YAML or Marshal.dump.
+    def serialize object
+      object.to_json
+    end
+
+    # Given a string, deserialize an object. By default this calls JSON.parse
+    # but could be overriden to use another deserialization method.
+    def self.deserialize str
+      str.nil? ? nil : JSON.parse(str)
+    end
+  
+    private
+    # Build the message to send to SQS
+    def sqs_message_body
+      {:contents => self.serialize(contents), :enqueued_at => enqueued_at}.to_json
+    end
+  
+    # Create a SQSMessage instance from its compnent parts
+    def self.create_from_raw_message queue_name, raw_message, received_at
+      message = self.new(queue_name)
+      data = self.parse_sqs_message_body(raw_message.body)
+    
+      message.contents = data['contents']
+      message.raw_message = raw_message
+      message.enqueued_at = data['enqueued_at']
+      message.received_at = received_at
+    
+      return message
+    end
+  
+    # Parse a RightAws SQS message body to the :contents, :enqueued_at hash needed to create a new message
+    def self.parse_sqs_message_body message_string
+      message = message_string.blank? ? {} : JSON.parse(message_string)
+      message['contents'] = self.deserialize(message['contents'])
+      return message
+    end
+  end
+end

data/lib/sqs/message_size_error.rb

@@ -0,0 +1,4 @@
+module SQS
+  class MessageSizeError < RuntimeError
+  end
+end

data/lib/sqs/queue.rb

@@ -0,0 +1,17 @@
+module SQS
+
+  # Call SQS::Queue['queue_name'] to retrieve a RightAws::SqsGen2 queue instance
+  module Queue
+  
+    def self.[] queue_name
+      @sqs ||= RightAws::SqsGen2.new(SQS::Config.access_key, SQS::Config.secret_access_key, :logger => self.logger)
+      @sqs.queue(queue_name, true)
+    end
+  
+    def self.logger
+      logger = Logger.new(STDOUT)
+      logger.level = Logger::FATAL
+      return logger
+    end
+  end
+end

data/lib/sqs/transport.rb

@@ -0,0 +1,176 @@
+module SQS
+
+  # Include the SQS::Transport mixin in a class to add SQS enqueue and dequeue capabilities.
+  #
+  # After including, call <tt>set_queue_name</tt> to specify which SQS queue will receive messages.
+  #
+  # There are two ways to define the data that will be included in queued messages:
+  # * call <tt>include_in_sqs_message</tt> with an array of attributes to include
+  # * implement <tt>to_sqs_message</tt> and return an :attr => value hash
+  #
+  # <tt>validate_message</tt> can be implemented to validate message data before it is pushed to SQS.
+  # If this method raises an exception, the message will not be queued.
+  #
+  # As an example:
+  #
+  #  class MyMessage
+  #    include SQS::Transport
+  #   
+  #    set_queue_name :widgets
+  #
+  #    attr_accessor :color, :size
+  #    include_in_sqs_message :color, :size
+  #
+  #    def validate_message
+  #      raise "Must have both size and color" if color.nil? || size.nil?
+  #    end
+  #
+  #  end
+  #
+  # creates a class that would then allow:
+  #
+  #  message = MyMessage.new
+  #  message.color = 'red'
+  #  message.size = 'xtrasmall'
+  #  message.queue!
+  #
+  # at which point a :size => trasmall, :color => red message would be pushed onto the "widgets" SQS queue
+  #
+  # A client using the same class could then call:
+  #
+  #  incoming = MyMessage.receive
+  #  puts incoming.color # "red"
+  #  puts incoming.size # "xtrasmall"
+  #  incoming.dequeue!  # message is removed from SQS queue
+  #
+  # Note that by default JSON serializtion is used, so some type semanitics are not preseved.
+  # For example, if you set <tt>incoming.color</tt> to <tt>{:shade => :red}</tt> the data would be received as a string (<tt>{'shade' => 'red'}</tt>)
+  # The serialization method is customizable by overriding <tt>serialize</tt> on SQS::Message.
+  #
+  # SQS::Transport stamps the enqueue and dequeue times, which can be used to calculate time in queue
+  #
+  #  puts incoming.enqueued_at # Mon Jul 06 22:16:15 UTC 2009
+  #  puts incoming.dequeued_at # Mon Jul 06 22:16:25 UTC 2009
+  #  puts incoming.time_in_queue # 10
+  #
+  # In addition, the class includes a <tt>peek</tt> method that can be used to inspect queued messages without removing them from the queue.
+  #
+  module Transport
+    
+    def self.included(base) # :nodoc:
+      base.extend ClassMethods
+    end
+  
+    module ClassMethods
+    
+      # Defines associated SQS queue
+      def set_queue_name name
+        @sqs_queue_name = name.to_s
+      end
+    
+      # Returns name of associated SQS Queue; raises exception if name has not yet been defined
+      def sqs_queue_name
+        raise "undefined queue name!" if @sqs_queue_name.nil?
+        @sqs_queue_name
+      end  
+    
+      # Defines the attributes to be included in the message sent to SQS. Not necessary if <tt>to_sqs_message</tt> is overridden.
+      def include_in_sqs_message *attrs_to_include
+        @attrs_for_sqs_message = attrs_to_include
+      end
+    
+      # Returns the list of attrs to be sent to SQS; raises an exception if attrs have not yet been defined.
+      def attrs_for_sqs_message
+        raise "Message requires at least one attribute. Call include_in_sqs_message to define which attributes are included in SQS message" if @attrs_for_sqs_message.nil? || @attrs_for_sqs_message.empty?
+        @attrs_for_sqs_message
+      end
+    
+      # Pops one or more messages off the SQS queue, parses the contents, and returns them as instances of the class.
+      #  * <tt>number_to_recieve</tt> is optional.  If not passed, a single message will be returned.  If number_to_receive == 1, a single instance will be returned; otherwise an array will be returned.
+      #
+      # Valid options:
+      # * <tt>:visiblity</tt> - sets the visiblity timeout on the message in seconds
+      def receive number_to_receive=1, opts={}
+        result = SQS::Message.receive(self.sqs_queue_name, number_to_receive, opts)
+      
+        if number_to_receive == 1
+          reconstitute_instance(result)
+        else
+          result.map {|m| reconstitute_instance(m)}
+        end
+      end
+    
+      def reconstitute_instance sqs_message
+        new_instance = self.new
+        sqs_message.contents.each { |field, value| new_instance.send("#{field}=", value) }
+        new_instance.sqs_message = sqs_message
+        return new_instance
+      end
+    
+      # Retrives one or more messages from the queue, but sets their visiblity to zero so that
+      # they can immediately be picked up by another worker. Useful for previewing messages on the queue.
+      # * <tt>queue_name</tt> is the name of the SQS queue
+      # * <tt>number_to_view</tt> sets the maximum number of messages to return. If set to 1, a single instance is returned; if > 1 an array is returned. Defaults to 1.
+      # No options at this time.
+      def peek number_to_view=1, opts={}
+        self.receive(number_to_view, opts.merge(:visibility => 0))
+      end
+    
+    end
+
+    attr_writer :sqs_message
+
+    # Returns a hash that will be serialized and sent to SQS. By default, returns a <tt>{'attr' => 'value'}</tt>
+    # hash containing all attributes defined by the <tt>include_in_sqs_message</tt> call.
+    #
+    # Override this to return a custom {'attr' => 'value'} hash for more control over serialization.
+    def to_sqs_message
+      Hash[*self.class.attrs_for_sqs_message.collect {|a| [a, self.send(a)]}.flatten]
+    end
+  
+    # Implement <tt>validate_message</tt> to check message data before it is sent to SQS.
+    # If this method raises an exception, message will not be queued.
+    def validate_message
+    end
+  
+    # Validates the message, then pushes it onto the associated queue.
+    # If validation raises an exception, the message will not be queued and the exception will bubble up.
+    def queue!
+      validate_message
+      sqs_message.contents = to_sqs_message
+      sqs_message.queue!
+    end
+  
+    # Removes a retrieved instance from the SQS queue.
+    def dequeue!
+     sqs_message.dequeue!
+    end
+
+    # Returns the associated SQS::Message instance
+    def sqs_message
+      @sqs_message ||= SQS::Message.new(self.class.sqs_queue_name)
+      return @sqs_message
+    end
+
+    # Returns the Amazon id for the SQS message.
+    def sqs_message_id
+      sqs_message.id
+    end
+
+    # Returns the time the message was queued
+    def enqueued_at
+      sqs_message.enqueued_at
+    end
+  
+    # Returns the time the message was dequeued
+    def dequeued_at
+      sqs_message.dequeued_at
+    end
+  
+    # Returns the amount of time a message spent in the queue, in seconds.
+    def time_in_queue
+      sqs_message.time_in_queue
+    end
+
+  end
+end

data/lib/sqs_transport.rb

@@ -0,0 +1,9 @@
+require 'json'
+require 'json/add/core'
+require 'right_aws'
+
+require File.join(File.dirname(__FILE__), 'sqs/config')
+require File.join(File.dirname(__FILE__), 'sqs/queue')
+require File.join(File.dirname(__FILE__), 'sqs/message_size_error')
+require File.join(File.dirname(__FILE__), 'sqs/message')
+require File.join(File.dirname(__FILE__), 'sqs/transport')

data/test/mock_queue.rb

@@ -0,0 +1,13 @@
+class MockQueue
+  
+  attr_accessor :messages
+  
+  def initialize
+    @messages = []
+  end
+  
+  def push message
+    messages << message
+  end
+  
+end

data/test/test_helper.rb

@@ -0,0 +1,15 @@
+require 'rubygems'
+require 'test/unit'
+require 'shoulda'
+require 'mocha'
+require 'time_warp' # on github as 'iridesco-time-warp'
+
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+require 'sqs_transport'
+require 'mock_queue'
+
+SQS::Config.access_key = 'test1234'
+SQS::Config.secret_access_key = 'ASDF KEY'
+
+class Test::Unit::TestCase
+end

data/test/test_sqs_config.rb

@@ -0,0 +1,57 @@
+require File.dirname(__FILE__) + '/test_helper'
+
+class TestSQSConfig < Test::Unit::TestCase
+  
+  context "defaults" do
+    setup do
+      SQS::Config.access_key = nil
+      SQS::Config.secret_access_key = nil
+    end
+    
+    
+    should "raise an ArgumentError if access_key is undefined" do
+      assert_raises(ArgumentError) { SQS::Config.access_key }
+    end
+    
+    should "raise an ArgumentError if secret_access_key is undefined" do
+      assert_raises(ArgumentError) { SQS::Config.secret_access_key }
+    end
+  end
+  
+  context "setters" do
+    should "return value for access_key if defined" do
+      SQS::Config.access_key = 'TeSt'
+      assert_equal 'TeSt', SQS::Config.access_key
+    end
+    
+    should "return value for secret_access_key if defined" do
+      SQS::Config.secret_access_key = 'TeStSecr3t'
+      assert_equal 'TeStSecr3t', SQS::Config.secret_access_key
+    end
+  end
+  
+  context "parse" do
+    should "set access_key if provided" do
+      SQS::Config.parse({'access_key' => '1234'})
+      assert_equal '1234', SQS::Config.access_key
+    end
+    
+    should "not set access_key if provided as blank string" do
+      SQS::Config.parse({'access_key' => '1234'})
+      SQS::Config.parse({'access_key' => ''})
+      assert_equal '1234', SQS::Config.access_key
+    end
+    
+    should "set secret_access_key if provided" do
+      SQS::Config.parse({'secret_access_key' => '1234ABC'})
+      assert_equal '1234ABC', SQS::Config.secret_access_key
+    end
+    
+    should "not set secret_access_key if provided as blank string" do
+      SQS::Config.parse({'secret_access_key' => '1234ABC'})
+      SQS::Config.parse({'secret_access_key' => ''})
+      assert_equal '1234ABC', SQS::Config.secret_access_key
+    end
+  end
+  
+end

data/test/test_sqs_message.rb

@@ -0,0 +1,221 @@
+require File.dirname(__FILE__) + '/test_helper'
+
+class SQS::Message
+  public :sqs_message_body
+end
+
+class TestSQSMessage < Test::Unit::TestCase
+  
+  context "self.receive" do
+     setup do
+       @mock_queue = MockQueue.new 
+       SQS::Queue.stubs(:[]).with('test_queue').returns(@mock_queue)
+     end
+     
+     should "call sqs_queue.recieve_messages for the specified number of messages" do
+       @mock_queue.expects(:receive_messages).with(7, anything).returns([])
+       SQS::Message.receive('test_queue', 7)
+     end
+     
+     should "call sqs_queue.receive for a single message if no message count is specified" do
+       @mock_queue.expects(:receive_messages).with(1, anything).returns([])
+       SQS::Message.receive('test_queue')
+     end
+     
+     should "call sqs_queue.receive with visibility specified as :visibility in options" do
+       @mock_queue.expects(:receive_messages).with(anything, 23).returns([])
+       SQS::Message.receive('test_queue', 1, :visibility => 23)
+     end
+     
+     should "call sqs_queue.receive with nil visiblity if :visiblity not provided in options" do
+       @mock_queue.expects(:receive_messages).with(anything, nil).returns([])
+       SQS::Message.receive('test_queue', 1)
+     end
+  
+     should "return a single instance of class if a single message is requested" do
+       @mock_queue.stubs(:receive_messages).returns([mock_message])
+       assert_kind_of SQS::Message, SQS::Message.receive('test_queue', 1)
+     end
+     
+     should "return an array of objects if multiple messages are requested" do
+       message_array = [mock_message, mock_message, mock_message]
+       @mock_queue.stubs(:receive_messages).returns(message_array)
+       assert_equal message_array, SQS::Message.receive('test_queue', 7)
+     end
+     
+     should "return an array of objects if multiple messages are requested, even if there is only a single message in the queue" do
+       message_array = [mock_message]
+       @mock_queue.stubs(:receive_messages).returns(message_array)
+       assert_equal message_array, SQS::Message.receive('test_queue', 7)
+     end
+     
+     should "set received_at on returned messages to the time dequeue! was invoked" do
+       message_array = [mock_message]
+       @mock_queue.stubs(:receive_messages).returns(message_array)
+  
+       expected_received_at = Time.now.utc - 5_000
+       received_message = nil
+  
+       pretend_now_is(expected_received_at) do
+         received_message = SQS::Message.receive('test_queue')
+       end
+       
+       assert_in_delta expected_received_at, received_message.received_at, 0.5
+     end
+     
+     should "stamp a consistent received_at across all messages returned" do
+       message_array = [mock_message, mock_message, mock_message]
+       @mock_queue.stubs(:receive_messages).returns(message_array)
+  
+       messages = SQS::Message.receive('test_queue', 3)
+       
+       assert_equal 1, messages.collect { |m| m.received_at }.uniq.length   
+     end
+     
+     should "assign the enqueued_at time on returned message" do
+       expected_message = SQS::Message.new 'test_queue'
+       expected_message.contents = {:value_1 => 1}
+       
+       @mock_queue.stubs(:receive_messages).returns([mock_message(expected_message.sqs_message_body)])
+       
+       message = SQS::Message.receive('test_queue')
+       assert_equal expected_message.enqueued_at, message.enqueued_at
+     end
+     
+     should "assign the contents on returned message" do
+       expected_message = SQS::Message.new 'test_queue'
+       expected_message.contents = {'value_1' => 1}
+       
+       @mock_queue.stubs(:receive_messages).returns([mock_message(expected_message.sqs_message_body)])
+       
+       message = SQS::Message.receive('test_queue')
+       assert_equal expected_message.contents, message.contents
+      end
+      
+      should "assign the raw message returned from SQS to raw_message" do
+        expected_message = mock()
+        expected_message.stubs(:body)
+        @mock_queue.stubs(:receive_messages).returns([expected_message])
+        message = SQS::Message.receive('test_queue')
+        assert_equal expected_message.object_id, message.raw_message.object_id
+      end
+   end
+   
+   context "self.peek" do
+     should "receive number_to_view with :visibility => 0" do
+       SQS::Message.expects(:receive).with('test_queue', 10, :visibility => 0)
+       SQS::Message.peek('test_queue', 10)
+     end
+     
+     should "receive 1 message with :visiblity => 0 if number_to_view not specified" do
+       SQS::Message.expects(:receive).with('test_queue', 1, :visibility => 0)
+       SQS::Message.peek('test_queue')
+     end
+   end
+  
+  context "queue!" do
+    setup do
+      @expected_contents = {:value_1 => 1, :value_2 => 2}
+      @mock_queue = MockQueue.new
+      SQS::Queue.stubs(:[]).with('test_queue').returns(@mock_queue)
+      @test_instance = SQS::Message.new 'test_queue'
+    end
+    
+    should "push a JSON message containing :content => serialized_content onto queue specified in init" do
+      @test_instance.contents = @expected_contents
+      @test_instance.queue!
+      
+      assert_equal @test_instance.serialize(@expected_contents), JSON.parse(@mock_queue.messages.first)['contents']
+    end
+    
+    should "push a JSON message containing :enqueue_time => Time.now.utc onto queue specified in init" do
+      enqueue_time = Time.now
+      
+      @test_instance.contents = {:value_1 => 1}
+      pretend_now_is(enqueue_time) do
+        @test_instance.queue!
+      end
+      
+      assert_equal enqueue_time.to_i, JSON.parse(@mock_queue.messages.first)['enqueued_at'].to_i
+    end
+    
+    should "raise a SQS::MessageSizeError if message contents are too big" do
+      @test_instance.stubs(:sqs_message_body).returns('a' * 10_000)
+      assert_raises(SQS::MessageSizeError) { @test_instance.queue! }
+    end
+  end
+  
+  context "dequeue!" do
+    should "call delete on the raw message" do
+      raw_message = mock()
+      raw_message.expects(:delete)
+      
+      instance = SQS::Message.new 'test_queue'
+      instance.stubs(:raw_message).returns(raw_message)
+      instance.dequeue!
+    end
+  end
+  
+  context "id" do
+    should "return the id from raw_message if it is set" do
+      expected_id = 'ASDF-1234'
+      raw_message = mock()
+      raw_message.stubs(:id).returns(expected_id)
+      
+      instance = SQS::Message.new 'test_queue'
+      instance.stubs(:raw_message).returns(raw_message)
+      
+      assert_equal expected_id, instance.id
+    end
+    
+    should "return nil if raw_message is not set" do
+      instance = SQS::Message.new 'test_queue'
+      instance.stubs(:raw_message).returns(nil)
+      assert_nil instance.id
+    end
+  end
+
+  context "queue_name" do
+    should "return the queue name specified at init time" do
+      expected_name = 'test_queue'
+      instance = SQS::Message.new expected_name
+      assert_equal expected_name, instance.queue_name
+    end
+  end
+  
+  context "time_in_queue" do
+   should "raise an ArgumentError if enqueued_at is nil" do
+     instance = SQS::Message.new 'test_queue'
+     instance.stubs(:enqueued_at).returns(nil)
+     instance.stubs(:received_at).returns(DateTime.now)
+     assert_raises(ArgumentError) { instance.time_in_queue }
+   end
+
+   should "raise an ArgumentError if received_at is nil" do
+     instance = SQS::Message.new 'test_queue'
+     instance.stubs(:enqueued_at).returns(nil)
+     instance.stubs(:received_at).returns(DateTime.now)
+     assert_raises(ArgumentError) { instance.time_in_queue }
+   end
+
+   should "return received_at - enqueued_at" do
+     instance = SQS::Message.new 'test_queue'
+   
+     expected_received_at = DateTime.now
+     expected_enqueued_at = expected_received_at - 200
+   
+     instance.stubs(:enqueued_at).returns(expected_enqueued_at)
+     instance.stubs(:received_at).returns(expected_received_at)
+     assert_equal expected_enqueued_at - expected_received_at, instance.time_in_queue
+   end
+  end
+  
+  private
+  def mock_message mock_body=nil
+    message = mock()
+    message.stubs(:body).returns(mock_body)
+    
+    return message
+  end
+  
+end

data/test/test_sqs_queue.rb

@@ -0,0 +1,52 @@
+require File.dirname(__FILE__) + '/test_helper'
+
+# Queue caches its RightAws instance; this needs to be busted between tests
+module SQS
+  module Queue
+    def self.flush_cache
+      @sqs = nil
+    end
+  end
+end
+
+class TestSQSQueue < Test::Unit::TestCase
+
+  def setup
+    @mock_right_aws = mock()
+    @mock_right_aws.stubs(:queue)
+  end
+
+  def teardown
+    SQS::Queue.flush_cache
+  end
+
+  should "instantiate a new RightAws::SQSGen2 using the access key from the SQS::Config" do
+    SQS::Config.access_key = 'ASDF'
+    RightAws::SqsGen2.expects(:new).with(SQS::Config.access_key, anything, anything).returns(@mock_right_aws)
+    SQS::Queue['test_queue']
+  end
+
+  should "instantiate a new RightAws::SQSGen2 using the secret access key from the SQS::Config" do
+    SQS::Config.secret_access_key = 'ASDF123'
+    RightAws::SqsGen2.expects(:new).with(anything, SQS::Config.secret_access_key, anything).returns(@mock_right_aws)
+    SQS::Queue['test_queue']
+  end
+  
+  should "make a find/create call for the specified queue" do
+    SQS::Config.secret_access_key = 'ASDF123'
+    RightAws::SqsGen2.stubs(:new).returns(@mock_right_aws)
+    @mock_right_aws.expects(:queue).with('test_queue', true)
+    SQS::Queue['test_queue']
+  end
+  
+  should "return a queue object" do
+    SQS::Config.secret_access_key = 'ASDF123'
+    RightAws::SqsGen2.stubs(:new).returns(@mock_right_aws)
+    
+    mock_queue = mock()
+    @mock_right_aws.stubs(:queue).returns(mock_queue)
+
+    assert_equal mock_queue.object_id, SQS::Queue['test_queue'].object_id
+  end
+
+end

data/test/test_sqs_transport.rb

@@ -0,0 +1,186 @@
+require File.dirname(__FILE__) + '/test_helper'
+
+class TestTransport
+  include SQS::Transport
+  
+  attr_reader :source_message # allow source to be read for testing
+  attr_accessor :value1, :value2
+  include_in_sqs_message :value1, :value2
+  
+  set_queue_name 'testQ'
+end
+
+class TestTransportNoQueue
+  include SQS::Transport
+  
+  attr_accessor :value1
+end
+
+class TestTransportSymbolQueue
+  include SQS::Transport
+  set_queue_name :testQueue2
+  
+  attr_accessor :value1
+  include_in_sqs_message :value1
+end
+
+
+class TestSQSTransport < Test::Unit::TestCase
+
+  context "self.sqs_queue_name" do
+    should "raise an exception if set_queue_name has not been called" do
+      assert_raises(RuntimeError) { TestTransportNoQueue.sqs_queue_name }
+    end
+    
+    should "return value set using set_queue_name" do
+      assert_equal 'testQ', TestTransport.sqs_queue_name
+    end
+    
+    should "return string, even if set_queue_name awas called with symbol" do
+      assert_equal 'testQueue2', TestTransportSymbolQueue.sqs_queue_name
+      assert_kind_of String, TestTransportSymbolQueue.sqs_queue_name
+    end
+  end
+
+  context "self.attrs_for_sqs_message" do
+    should "raise an exception if include_in_sqs_message has not been called" do
+      assert_raises(RuntimeError) { TestTransportNoQueue.attrs_for_sqs_message }
+    end
+    
+    should "return value set using include_in_sqs_message" do
+      assert_equal [:value1, :value2], TestTransport.attrs_for_sqs_message
+    end
+  end
+
+  context "self.receive" do
+    should "proxy request to SQS::Message.receive" do
+      SQS::Message.expects(:receive).with(TestTransport.sqs_queue_name, 5, :visibility => 10).returns([])
+      TestTransport.receive(5, :visibility => 10)
+    end
+        
+    should "return reconstituted instance of original if number_to_receive = 1" do
+      original = TestTransport.new
+      original.value1 = 'test'
+      original.value2 = 10
+      
+      SQS::Message.any_instance.stubs(:queue!)
+      original.queue!
+      SQS::Message.stubs(:receive).returns(original.sqs_message)
+      
+      new_instance = TestTransport.receive
+      assert_equal original.value1, new_instance.value1
+      assert_equal original.value2, new_instance.value2
+    end
+    
+    should "set the new instance's sqs_message = received message" do
+      original = TestTransport.new
+      original.value1 = 'test'
+      original.value2 = 10
+      
+      SQS::Message.any_instance.stubs(:queue!)
+      original.queue!
+      SQS::Message.stubs(:receive).returns(original.sqs_message)
+      
+      new_instance = TestTransport.receive
+      assert_equal original.sqs_message, new_instance.sqs_message
+    end
+    
+    should "return array of reconstituted originals if number_to_receive > 1" do
+      originals = []
+      
+      original1 = TestTransport.new
+      original1.value1 = 'test'
+      original1.value2 = 10
+      originals << original1
+      
+      original2 = TestTransport.new
+      original2.value1 = 'test2'
+      original2.value2 = 20
+      originals << original2
+      
+      SQS::Message.any_instance.stubs(:queue!)
+      originals.each {|o| o.queue!}
+      SQS::Message.stubs(:receive).returns(originals.collect {|o| o.sqs_message})
+      
+      instances = TestTransport.receive(3)
+      instances.each_with_index do |actual, i|
+        assert_equal originals[i].value1, actual.value1
+        assert_equal originals[i].value2, actual.value2
+      end
+    end
+  end
+  
+  context "self.peek" do
+    should "call self.receive with :visibility => 0" do
+      TestTransport.expects(:receive).with(5, :visibility => 0)
+      TestTransport.peek(5)
+    end
+    
+    should "receive a single instance by default" do
+      TestTransport.expects(:receive).with(1, :visibility => 0)
+      TestTransport.peek
+    end
+  end
+  
+  context "queue!" do
+    setup do
+      @test_instance = TestTransport.new
+      @test_instance.value1 = 'test1'
+      @test_instance.value2 = 'test2'
+      SQS::Message.any_instance.stubs(:queue!)
+    end
+    
+    should "call validate_message" do
+      @test_instance.expects(:validate_message)
+      @test_instance.queue!
+    end
+    
+    should "not call sqs_message.queue! if validate message throws exception" do
+      @test_instance.stubs(:validate_message).raises(RuntimeError)
+      SQS::Message.any_instance.expects(:queue!).never
+      begin
+        @test_instance.queue!
+      rescue
+      end
+    end
+    
+    should "set sqs_message.contents = to_sqs_message" do
+      @test_instance.queue!
+      assert_equal @test_instance.to_sqs_message, @test_instance.sqs_message.contents
+    end
+    
+    should "invoke queue! on the sqs_message" do
+      @test_instance.sqs_message.expects(:queue!)
+      @test_instance.queue!
+    end
+  end
+  
+  context "to_sqs_message - default implementation" do
+    should "return attrs_for_sqs_message in hash, with attrs as keys and values as values" do
+      instance = TestTransport.new
+      instance.value1 = '1234'
+      instance.value2 = 'abcd'
+      
+      assert_equal({:value1 => '1234', :value2 => 'abcd'}, instance.to_sqs_message)
+    end
+  end
+  
+  context "proxy to SQS::Message instance" do
+    setup do
+      @test_instance = TestTransport.new
+    end
+    
+    should "proxy sqs_message_id to sqs_message.id" do
+      @test_instance.sqs_message.expects(:id)
+      @test_instance.sqs_message_id
+    end
+    
+    ['dequeue!','enqueued_at','dequeued_at','time_in_queue'].each do |proxy_method|
+      should "proxy #{proxy_method} to sqs_message.#{proxy_method}" do
+        @test_instance.sqs_message.expects(proxy_method)
+        @test_instance.send(proxy_method)
+      end
+    end
+  end
+
+end

metadata

@@ -0,0 +1,87 @@
+--- !ruby/object:Gem::Specification 
+name: sqs_transport
+version: !ruby/object:Gem::Version 
+  version: 1.0.0
+platform: ruby
+authors: 
+- Ben Koski
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-07-10 00:00:00 -04:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: json
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: right_aws
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+description: Provides simple enqueue/dequeue facilities for Amazon SQS.
+email: gems@benkoski.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- lib/sqs
+- lib/sqs_transport.rb
+- lib/sqs/config.rb
+- lib/sqs/message.rb
+- lib/sqs/message_size_error.rb
+- lib/sqs/queue.rb
+- lib/sqs/transport.rb
+- test/mock_queue.rb
+- test/test_helper.rb
+- test/test_sqs_config.rb
+- test/test_sqs_message.rb
+- test/test_sqs_queue.rb
+- test/test_sqs_transport.rb
+- README
+- LICENSE
+has_rdoc: true
+homepage: http://github.com/bkoski/sqs_transport
+post_install_message: 
+rdoc_options: 
+- --inline-source
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.1
+signing_key: 
+specification_version: 2
+summary: Provides simple enqueue/dequeue facilities for Amazon SQS.
+test_files: []
+