aws_sdk 3.1.5

data/lib/aws/sqs/queue_collection.rb

@@ -0,0 +1,170 @@
+# Copyright 2011-2012 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"). You
+# may not use this file except in compliance with the License. A copy of
+# the License is located at
+#
+#     http://aws.amazon.com/apache2.0/
+#
+# or in the "license" file accompanying this file. This file is
+# distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
+# ANY KIND, either express or implied. See the License for the specific
+# language governing permissions and limitations under the License.
+
+module AWS
+  class SQS
+
+    # Represents all the {Queue} objects in your account.
+    #
+    # If you have permission to access a queue created by another
+    # account, you can also use this collection to access that queue
+    # by URL.
+    #
+    # @example Printing the URLs of all queues
+    #   pp sqs.queues.map(&:url)
+    #
+    # @example Filtering queues by queue name prefix
+    #   pp sqs.queues.with_prefix("production_").map(&:url)
+    #
+    # @example Accessing a queue by URL
+    #   url = "http://sqs.us-east-1.amazonaws.com/123456789012/myqueue"
+    #   sqs.queues[url].send_message("HELLO")
+    class QueueCollection
+
+      include Core::Model
+      include Enumerable
+
+      # @private
+      def initialize(opts = {})
+        @prefix = opts[:prefix]
+        super
+      end
+
+      # @return [String] The queue name prefix by which this
+      #   collection is filtered.
+      attr_reader :prefix
+
+      # Creates a new queue.
+      #
+      # @note If you delete a queue, you must wait at least 60
+      #   seconds before creating a queue with the same name.
+      #
+      # @param [String] name The name to use for the queue created.
+      #   Constraints: Maximum 80 characters; alphanumeric
+      #   characters, hyphens (-), and underscores (_) are allowed.
+      #
+      #   The name of the queue should be unique within your account.  If
+      #   you provide the name of an existing queue with the same options
+      #   it was created with then no error is raised and the existing
+      #   queue will be returned.
+      #
+      # @param [Hash] options
+      #
+      # @option options [Integer] :visibility_timeout (30) The number of 
+      #   seconds a message received from a queue will be invisible to 
+      #   others when they ask to receive messages.
+      #
+      # @option options [Policy] :policy A policy object or policy desription
+      #   (a json string).
+      #
+      # @option options [Integer] :maximum_message_size (65536) The maximum
+      #   number of bytes a message can contain before Amazon SQS rejects 
+      #   it.
+      #
+      # @option options [Integer] :delay_seconds The time in seconds that 
+      #   the delivery of all messages in the queue will be delayed.
+      #   This can be overriden when sending a message to the queue.
+      #
+      # @option options [Integer] :message_retention_period The number of
+      #   seconds from 60 (1 minute) to 1209600 (14 days).  The default
+      #   is 345600 (4 days).
+      #
+      # @return [Queue] The newly created queue.
+      #
+      def create name, options = {}
+
+        # SQS removed the default prefix to the visibility timeout option
+        # in the 2011-10-01 update -- this allows us to not break existing
+        # customers.
+        if options[:default_visibility_timeout]
+          options[:visibility_timeout] = 
+            options.delete(:default_visibility_timeout)
+        end
+
+        if policy = options[:policy]
+          options[:policy] = policy.to_json unless policy.is_a?(String)
+        end
+
+        client_opts = {}
+        client_opts[:queue_name] = name
+        unless options.empty?
+          client_opts[:attributes] = options.inject({}) do |attributes,(k,v)|
+            attributes.merge(Core::Inflection.class_name(k.to_s) => v.to_s)
+          end
+        end
+
+        response = client.create_queue(client_opts)
+
+        Queue.new(response[:queue_url], :config => config)
+
+      end
+
+      # @yieldparam [Queue] queue Each {Queue} object in the collection.
+      def each(&block)
+        options = {}
+        options[:queue_name_prefix] = prefix if prefix
+        client.list_queues(options)[:queue_urls].each do |url|
+          queue = self[url]
+          yield(queue)
+        end
+      end
+
+      # @param [String] prefix The queue name prefix.
+      # @return [QueueCollection] A new collection representing only
+      #   the queues whose names start with the given prefix.
+      def with_prefix(prefix)
+        self.class.new(:prefix => prefix, :config => config)
+      end
+
+      # @return [Queue] The queue with the given URL.
+      def [] url
+        Queue.new(url, :config => config)
+      end
+      
+      # Returns the queue with the given name.  This requires making
+      # a request to SQS to get the queue url.  If you know the url,
+      # you should use {#[]} instead.
+      #
+      #   queue = AWS::SQS.new.queues.named('my-queue')
+      #
+      # @param (see #url_for)
+      # @option (see #url_for)
+      # @return [Queue] Returns the queue with the given name.
+      def named queue_name, options = {}
+        self[url_for(queue_name, options = {})]
+      end
+
+      # Returns the url for the given queue.
+      #
+      #   sqs.queues.url_for('my-queue') 
+      #   #=> "https://sqs.us-east-1.amazonaws.com/123456789012/my-queue" 
+      #
+      # @param [String] queue_name The name of the queue you need a URL for.
+      #
+      # @param [Hash] options
+      #
+      # @option options [String] :queue_owner_aws_account_id The AWS account
+      #   ID of the account that created the queue.  You can only get the
+      #   url for queues in other accounts when the account owner has
+      #   granted you permission.
+      #
+      def url_for queue_name, options = {}
+        client_opts = {}
+        client_opts[:queue_name] = queue_name
+        client.get_queue_url(client_opts.merge(options))[:queue_url]
+      end
+
+    end
+
+  end
+end

data/lib/aws/sqs/received_message.rb

@@ -0,0 +1,181 @@
+# Copyright 2011-2012 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"). You
+# may not use this file except in compliance with the License. A copy of
+# the License is located at
+#
+#     http://aws.amazon.com/apache2.0/
+#
+# or in the "license" file accompanying this file. This file is
+# distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
+# ANY KIND, either express or implied. See the License for the specific
+# language governing permissions and limitations under the License.
+
+module AWS
+  class SQS
+
+    # Represents a message received from an Amazon SQS Queue.
+    class ReceivedMessage
+
+      include Core::Model
+
+      # @return [Queue] The queue from which this message was
+      #   received.
+      attr_reader :queue
+
+      # @return [String] The ID of the message.
+      attr_reader :id
+
+      # @return [String] A string associated with this specific
+      #   instance of receiving the message.
+      attr_reader :handle
+
+      # @return [String] The message's contents.
+      attr_reader :body
+
+      # @return [String] An MD5 digest of the message body.
+      attr_reader :md5
+
+      # @private
+      attr_reader :attributes
+
+      # @private
+      ATTRIBUTE_ALIASES = {
+        :sent_at => :sent_timestamp,
+        :receive_count => :approximate_receive_count,
+        :first_received_at => :approximate_first_receive_timestamp
+      }
+
+      # @private
+      def initialize(queue, id, handle, opts = {})
+        @queue = queue
+        @id = id
+        @handle = handle
+        @body = opts[:body]
+        @md5 = opts[:md5]
+        @attributes = opts[:attributes] || {}
+        super
+      end
+
+      # When SNS publishes messages to SQS queues the message body is
+      # formatted as a json message and then base 64 encoded.
+      # An easy way to work with SNS messages is to call this method:
+      #
+      #   sns_msg = message.as_sns_message
+      # 
+      #   sns_msg.topic
+      #   #=> <AWS::SNS::Topic ...>
+      #
+      #   sns_msg.to_h.inspect
+      #   #=> { :body => '...', :topic_arn => ... }
+      #
+      # @return [ReceivedSNSMessage]
+      def as_sns_message
+        ReceivedSNSMessage.new(body, :config => config)
+      end
+
+      # Deletes the message from the queue.  Even if the message is
+      # locked by another reader due to the visibility timeout
+      # setting, it is still deleted from the queue.  If you leave a
+      # message in the queue for more than 4 days, SQS automatically
+      # deletes it.
+      #
+      # If you use {Queue#poll} or {Queue#receive_message} in block
+      # form, the messages you receive will be deleted automatically
+      # unless an exception occurs while you are processing them.
+      # You can still use this method if you want to delete a
+      # message early and then continue processing it.
+      #
+      # @note It is possible you will receive a message even after
+      #   you have deleted it. This might happen on rare occasions
+      #   if one of the servers storing a copy of the message is
+      #   unavailable when you request to delete the message. The
+      #   copy remains on the server and might be returned to you
+      #   again on a subsequent receive request. You should create
+      #   your system to be idempotent so that receiving a
+      #   particular message more than once is not a problem.
+      #
+      # @return [nil]
+      def delete
+        client.delete_message(
+          :queue_url => queue.url, 
+          :receipt_handle => handle)
+        nil
+      end
+
+      # Changes the visibility timeout of a specified message in a
+      # queue to a new value. The maximum allowed timeout value you
+      # can set the value to is 12 hours. This means you can't
+      # extend the timeout of a message in an existing queue to more
+      # than a total visibility timeout of 12 hours. (For more
+      # information visibility timeout, see {Visibility
+      # Timeout}[http://docs.amazonwebservices.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/IntroductionArticle.html#AboutVT]
+      # in the Amazon SQS Developer Guide.)
+      #
+      # For example, let's say the timeout for the queue is 30
+      # seconds, and you receive a message. Once you're 20 seconds
+      # into the timeout for that message (i.e., you have 10 seconds
+      # left), you extend it by 60 seconds by calling this method
+      # with +timeout+ set to 60 seconds. You have then changed the
+      # remaining visibility timeout from 10 seconds to 60 seconds.
+      #
+      # @note If you attempt to set the timeout to an amount more
+      #   than the maximum time left, Amazon SQS returns an
+      #   error. It will not automatically recalculate and increase
+      #   the timeout to the maximum time remaining.
+      #
+      # @note Unlike with a queue, when you change the visibility
+      #   timeout for a specific message, that timeout value is
+      #   applied immediately but is not saved in memory for that
+      #   message. If you don't delete a message after it is
+      #   received, the visibility timeout for the message the next
+      #   time it is received reverts to the original timeout value,
+      #   not the value you set with this method.
+      #
+      # @return Returns the timeout argument as passed.
+      #
+      def visibility_timeout=(timeout)
+        client.change_message_visibility(
+          :queue_url => queue.url,
+          :receipt_handle => handle,
+          :visibility_timeout => timeout
+        )
+        timeout
+      end
+
+      # @return [String] The AWS account number (or the IP address,
+      #   if anonymous access is allowed) of the sender.
+      def sender_id
+        attributes["SenderId"]
+      end
+
+      # @return [Time] The time when the message was sent.
+      def sent_timestamp
+        @sent_at ||=
+          (timestamp = attributes["SentTimestamp"] and
+           Time.at(timestamp.to_i / 1000.0)) || nil
+      rescue RangeError => e
+        p [timestamp, timestamp.to_i]
+      end
+      alias_method :sent_at, :sent_timestamp
+
+      # @return [Integer] The number of times a message has been
+      #   received but not deleted.
+      def approximate_receive_count
+        (count = attributes["ApproximateReceiveCount"] and
+         count.to_i) or nil
+      end
+      alias_method :receive_count, :approximate_receive_count
+
+      # @return [Time] The time when the message was first received.
+      def approximate_first_receive_timestamp
+        @received_at ||=
+          (timestamp = attributes["ApproximateFirstReceiveTimestamp"] and
+           Time.at(timestamp.to_i / 1000.0)) || nil
+      end
+      alias_method :first_received_at, :approximate_first_receive_timestamp
+
+    end
+
+  end
+end

data/lib/aws/sqs/received_sns_message.rb

@@ -0,0 +1,112 @@
+# Copyright 2011-2012 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"). You
+# may not use this file except in compliance with the License. A copy of
+# the License is located at
+#
+#     http://aws.amazon.com/apache2.0/
+#
+# or in the "license" file accompanying this file. This file is
+# distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
+# ANY KIND, either express or implied. See the License for the specific
+# language governing permissions and limitations under the License.
+
+require 'time'
+require 'base64'
+
+module AWS
+  class SQS
+
+    # Represents message published from an {SNS::Topic} to an {SQS::Queue}.
+    class ReceivedSNSMessage
+
+      include Core::Model
+
+      # @param [String] body The SQS message body
+      #   from a message published by SNS.
+      # @param [Hash] options
+      def initialize body, options = {}
+        @body = body
+        super
+      end
+
+      # @return [String] Returns the JSON hash (as a string) as was
+      #   published by SNS.  See {#body} to get the decoded message
+      #   or {#to_h} to get the decoded JSON hash as a ruby hash.
+      def raw_message
+        @body
+      end
+
+      # @return[String] Returns the decoded message as was published.
+      def body
+        to_h[:body]
+      end
+
+      # @return [String] Returns the ARN for the topic that published this
+      #   message.
+      def topic_arn
+        to_h[:topic_arn]
+      end
+
+      # @return [SNS::Topic] Returns the topic that published this message.
+      def topic
+        SNS::Topic.new(topic_arn, :config => config)
+      end
+
+      # @return [String] Returns the message type.
+      def message_type
+        to_h[:message_type]
+      end
+
+      # @return [String] Returns the calculated signature for the message.
+      def signature
+        to_h[:signature]
+      end
+
+      # @return [String] Returns the signature version.
+      def signature_version
+        to_h[:signature_version]
+      end
+
+      # @return [Time] Returns the time the message was published at by SNS.
+      #   by SNS.
+      def published_at
+        to_h[:published_at]
+      end
+
+      # @return [String] Returns the unique id of the SNS message.
+      def message_id
+        to_h[:message_id]
+      end
+
+      # @return [String] Returns the url for the signing cert.
+      def signing_cert_url
+        to_h[:signing_cert_url]
+      end
+
+      # @return [String] Returns the url you can request to unsubscribe message
+      #   from this queue.
+      def unsubscribe_url
+        to_h[:unsubscribe_url]
+      end
+
+      # @return [Hash] Returns the decoded message as a hash.
+      def to_h
+        data = JSON.parse(@body)
+        {
+          :body => data['Message'],
+          :topic_arn => data['TopicArn'],
+          :message_type => data['Type'],
+          :signature => data['Signature'],
+          :signature_version => data['SignatureVersion'],
+          :published_at => Time.parse(data['Timestamp']),
+          :message_id => data['MessageId'],
+          :signing_cert_url => data['SigningCertURL'],
+          :unsubscribe_url => data['UnsubscribeURL'],
+        }
+      end
+
+    end
+
+  end
+end