dustMason-right_aws 2.1.0

data/lib/sns/right_sns.rb

@@ -0,0 +1,205 @@
+#
+# Copyright (c) 2007-2008 RightScale Inc
+#
+# Permission is hereby granted, free of charge, to any person obtaining
+# a copy of this software and associated documentation files (the
+# "Software"), to deal in the Software without restriction, including
+# without limitation the rights to use, copy, modify, merge, publish,
+# distribute, sublicense, and/or sell copies of the Software, and to
+# permit persons to whom the Software is furnished to do so, subject to
+# the following conditions:
+#
+# The above copyright notice and this permission notice shall be
+# included in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+# LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+# WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+#
+
+module RightAws
+
+    #
+    # = RightAws::Sns -- RightScale's Amazon SNS interface
+    # The RightAws::Sns class provides a complete interface to Amazon's Simple
+    # Notification Service.
+    # For explanations of the semantics
+    # of each call, please refer to Amazon's documentation at
+    # http://docs.amazonwebservices.com/sns/2010-03-31/api/
+    #
+    # Error handling: all operations raise an RightAws::AwsError in case
+    # of problems. Note that transient errors are automatically retried.
+    #
+    #  sns    = RightAws::Sns.new(aws_access_key_id, aws_secret_access_key)
+    #  topics = sns.topics #=> [<Sns::Topic>, <Sns::Topic>]
+    #  topic1 = sns.create_topic('bananas') #=> <Sns::Topic>
+    #  topic1.subscribe('email', 'john@example.com') #=> true
+    #   ...
+    #  topic1.send_message('Some content', 'An optional subject')
+    #       
+    # Params is a hash:
+    #
+    #    {:server       => 'sns.us-east-1.amazonaws.com' # Amazon service host: 'sns.us-east-1.amazonaws.com' (default)
+    #     :port         => 443                   # Amazon service port: 80 or 443 (default)
+    #     :multi_thread => true|false            # Multi-threaded (connection per each thread): true or false (default)
+    #     :signature_version => '0'              # The signature version : '0' or '1'(default)
+    #     :logger       => Logger Object}        # Logger instance: logs to STDOUT if omitted }
+    #
+  class Sns
+    attr_reader :interface
+    
+    def initialize(aws_access_key_id=nil, aws_secret_access_key=nil, params={})
+      @interface = SnsInterface.new(aws_access_key_id, aws_secret_access_key, params)
+    end
+    
+      # Retrieves a list of topics.
+      # Returns an +array+ of +Topic+ instances.
+      #
+      #  RightAws::Sns.topics #=> array of topics
+      #
+    def topics
+      @interface.list_topics.map do |arn|
+        Topic.new(self, arn)
+      end
+    end
+    
+      # Returns Topic instance by ARN. 
+    def topic(arn)
+      Topic.new(self, arn)
+    end
+    
+      # Creates a new topic.
+    def create_topic(name)
+      @interface.create_topic(self, name)
+    end
+  
+    class Topic
+      attr_reader :arn, :sns
+        
+        # Creates new Topic instance. 
+        # Does not create a topic at Amazon.
+        #
+        #  topic = RightAws::Sns::Topic.new(sns, 'arn%3Aaws%3Asns%3Aus-east-1%3A123456789012%3AMy-Topic')
+        #
+      def initialize(sns, arn)
+        @sns = sns
+        @arn = arn
+      end
+      
+        # Deletes queue. 
+        # Queue must be empty or +force+ must be set to +true+. 
+        # Returns +true+. 
+        #
+        #  queue.delete(true) #=> true
+        #
+      def delete
+        @sns.interface.delete_topic(arn)
+      end
+      alias_method :destroy, :delete
+      
+        # Sends new message to topic. 
+        # Returns new Message instance that has been sent to topic.
+      def send_message(body, subject = nil)
+        @sns.interface.send_message(arn, body, subject)
+      end
+      alias_method :push, :send_message
+      
+        # Returns the AWS account ID of the topic's owner
+      def owner
+        topic_attributes['Owner']
+      end
+      
+        # Returns the JSON serialization of the topic's access control policy
+      def policy
+        unless !topic_attributes['Policy'] || topic_attributes['Policy'].length == 0
+          JSON.parse(topic_attributes['Policy'])
+        end
+      end
+      
+        # Returns the human-readable name used in the "From" field for
+        # notifications to email and email-json endpoints
+      def display_name
+        topic_attributes['DisplayName']
+      end
+      
+        # Sets the display name
+      def display_name=(value)
+        set_topic_attribute('DisplayName', value)
+      end
+      
+        # Returns a hash in the format:
+        # { :set => [<Sns::Member>, <Sns::Member>, <Sns::Member>], :next => '123' }
+        #
+        # Accepts an optional next_token telling where to start from
+      def subscriptions(next_token = nil)
+        @sns.interface.list_subscriptions_by_topic(arn, next_token)
+      end
+      
+        # Returns a <Member> object
+      def subscribe(protocol, end_point)
+        raise StandardError, "Protocol (#{protocol}) is not valid" unless ['http', 'https', 'email', 'email-json', 'sqs']
+        @sns.interface.subscribe_to_topic(arn, protocol, end_point)
+      end
+      
+        # Gives another AWS account holder access to set actions within your account
+      def add_permission(label, account_ids, actions)
+        account_ids = [account_ids.to_s] unless account_ids.kind_of?(Array)
+        actions     = [actions.to_s]     unless actions.kind_of?(Array)
+        @sns.interface.add_permissions(arn, label, account_ids, actions)
+      end
+      
+        # Removes permission from another AWS account holder
+      def remove_permission(label)
+        @sns.interface.remove_permissions(arn, label)
+      end
+      
+        # Confirms a subscription (if you don't have the <Sns::Member> object)
+      def confirm_subscription(token, authenticate_on_unsubscribe = false)
+        member               = Member.new
+        member.sns_interface = @sns.interface
+        member.topic_arn     = arn
+        member.token         = token
+        
+        member.confirm(authenticate_on_unsubscribe)
+      end
+
+      private
+      def set_topic_attribute(name, value)
+        if @sns.interface.set_topic_attributes(arn, name, value)
+          @topic_attributes     ||= {}
+          @topic_attributes[name] = value
+        end
+      end
+      
+      def topic_attributes
+        @topic_attributes ||= @sns.interface.get_topic_attributes(arn)
+      end
+    end
+    
+    
+    class Message
+      attr_reader :topic, :id, :body, :subject
+      
+      def initialize(topic, id = nil, body = nil, subject = nil)
+        @topic       = topic
+        @id          = id
+        @body        = body
+        @subject     = subject
+      end
+    end
+    
+    class Member
+      attr_accessor :sns_interface, :topic_arn, :token
+      
+      def confirm(authenticate_on_unsubscribe = false)
+        sns_interface.confirm_subscription(topic_arn, token, authenticate_on_unsubscribe)
+      end
+    end
+    
+  end
+  
+end

data/lib/sns/right_sns_interface.rb

@@ -0,0 +1,343 @@
+#
+# Copyright (c) 2007-2008 RightScale Inc
+#
+# Permission is hereby granted, free of charge, to any person obtaining
+# a copy of this software and associated documentation files (the
+# "Software"), to deal in the Software without restriction, including
+# without limitation the rights to use, copy, modify, merge, publish,
+# distribute, sublicense, and/or sell copies of the Software, and to
+# permit persons to whom the Software is furnished to do so, subject to
+# the following conditions:
+#
+# The above copyright notice and this permission notice shall be
+# included in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+# LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+# WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+#
+
+module RightAws
+
+  #
+  # Right::Aws::SnsInterface - RightScale's low-level Amazon SNS interface
+  #
+
+  class SnsInterface < RightAwsBase
+    include RightAwsBaseInterface
+    
+    API_VERSION       = "2010-03-31"
+    DEFAULT_HOST      = "sns.us-east-1.amazonaws.com"
+    DEFAULT_PORT      = 443
+    DEFAULT_PROTOCOL  = 'https'
+    REQUEST_TTL       = 30
+    DEFAULT_VISIBILITY_TIMEOUT = 30
+
+
+    @@bench = AwsBenchmarkingBlock.new
+    def self.bench_xml
+      @@bench.xml
+    end
+    def self.bench_sns
+      @@bench.service
+    end
+
+    @@api = API_VERSION
+    def self.api 
+      @@api
+    end
+
+    # Creates a new SnsInterface instance. This instance is limited to
+    # operations on SNS objects created with Amazon's 2008-01-01 API version.  This
+    # interface will not work on objects created with prior API versions.  See
+    # Amazon's article "Migrating to Amazon SNS API version 2008-01-01" at:
+    # http://developer.amazonwebservices.com/connect/entry.jspa?externalID=1148
+    #
+    #  sqs = RightAws::SnsInterface.new('1E3GDYEOGFJPIT75KDT40','hgTHt68JY07JKUY08ftHYtERkjgtfERn57DFE379', {:multi_thread => true, :logger => Logger.new('/tmp/x.log')}) 
+    #  
+    # Params is a hash:
+    #
+    #    {:server       => 'sns.us-east-1.amazonaws.com' # Amazon service host: 'sns.us-east-1.amazonaws.com' (default)
+    #     :port         => 443                   # Amazon service port: 80 or 443 (default)
+    #     :multi_thread => true|false            # Multi-threaded (connection per each thread): true or false (default)
+    #     :signature_version => '0'              # The signature version : '0', '1' or '2'(default)
+    #     :logger       => Logger Object}        # Logger instance: logs to STDOUT if omitted }
+    #
+    def initialize(aws_access_key_id=nil, aws_secret_access_key=nil, params={})
+      init({ :name             => 'SNS', 
+             :default_host     => ENV['SNS_URL'] ? URI.parse(ENV['SNS_URL']).host   : DEFAULT_HOST, 
+             :default_port     => ENV['SNS_URL'] ? URI.parse(ENV['SNS_URL']).port   : DEFAULT_PORT, 
+             :default_protocol => ENV['SNS_URL'] ? URI.parse(ENV['SNS_URL']).scheme : DEFAULT_PROTOCOL }, 
+           aws_access_key_id     || ENV['AWS_ACCESS_KEY_ID'], 
+           aws_secret_access_key || ENV['AWS_SECRET_ACCESS_KEY'], 
+           params)
+    end
+
+
+  #-----------------------------------------------------------------
+  #      Requests
+  #-----------------------------------------------------------------
+
+    # Generates a request hash for the query API
+    def generate_request(action, param={})  # :nodoc:
+      # For operation requests on a topic, the queue URI will be a parameter,
+      # so we first extract it from the call parameters.  Next we remove any
+      # parameters with no value or with symbolic keys.  We add the header
+      # fields required in all requests, and then the headers passed in as
+      # params.  We sort the header fields alphabetically and then generate the
+      # signature before URL escaping the resulting query and sending it.
+      service = param[:queue_url] ? URI(param[:queue_url]).path : '/'
+      param.each{ |key, value| param.delete(key) if (value.nil? || key.is_a?(Symbol)) }
+      service_hash = { "Action"           => action,
+                       "Expires"          => (Time.now + REQUEST_TTL).utc.strftime("%Y-%m-%dT%H:%M:%SZ"),
+                       "AWSAccessKeyId"   => @aws_access_key_id,
+                       "Version"          => API_VERSION }
+      service_hash.update(param)
+      service_params = signed_service_params(@aws_secret_access_key, service_hash, :get, @params[:server], service)
+      request        = Net::HTTP::Get.new("#{AwsUtils.URLencode(service)}?#{service_params}")
+        # prepare output hash
+      { :request  => request, 
+        :server   => @params[:server],
+        :port     => @params[:port],
+        :protocol => @params[:protocol] }
+    end
+
+    def generate_post_request(action, param={})  # :nodoc:
+      service = param[:queue_url] ? URI(param[:queue_url]).path : '/'
+      message   = param[:message]                # extract message body if nesessary
+      param.each{ |key, value| param.delete(key) if (value.nil? || key.is_a?(Symbol)) }
+      service_hash = { "Action"           => action,
+                       "Expires"          => (Time.now + REQUEST_TTL).utc.strftime("%Y-%m-%dT%H:%M:%SZ"),
+                       "AWSAccessKeyId"   => @aws_access_key_id,
+                       "MessageBody"      => message,
+                       "Version"          => API_VERSION }
+      service_hash.update(param)
+      #
+      service_params = signed_service_params(@aws_secret_access_key, service_hash, :post, @params[:server], service)
+      request        = Net::HTTP::Post.new(AwsUtils::URLencode(service))
+      request['Content-Type'] = 'application/x-www-form-urlencoded' 
+      request.body = service_params
+        # prepare output hash
+      { :request  => request, 
+        :server   => @params[:server],
+        :port     => @params[:port],
+        :protocol => @params[:protocol] }
+    end
+
+
+      # Sends request to Amazon and parses the response
+      # Raises AwsError if any banana happened
+    def request_info(request, parser) # :nodoc:
+      request_info_impl(:sqs_connection, @@bench, request, parser)
+    end
+
+      # Creates a new topic, returning the new Topic object.
+      #
+      #  sqs.create_topic('my_awesome_queue') #=> 'https://queue.amazonaws.com/ZZ7XXXYYYBINS/my_awesome_queue'
+      #
+    def create_topic(sns, topic_name)
+      req_hash = generate_request('CreateTopic', 'Name' => topic_name)
+      arn = request_info(req_hash, SnsCreateTopicParser.new(:logger => @logger))
+      Sns::Topic.new(sns, arn)
+    rescue
+      on_exception
+    end
+
+     # Lists all topics owned by this user
+     # Topic creation is an eventual operation and created topics may not show up in immediately subsequent list_topic calls.
+     #
+     #  sns.list_queues() #=> ['ZZ7XXXYYYBINS','ZZ7XXXYYYBINS']
+     #
+    def list_topics
+      req_hash = generate_request('ListTopics')
+      request_info(req_hash, SnsListTopicsParser.new(:logger => @logger))
+    rescue
+      on_exception
+    end
+      
+      # Deletes topic. Any messages in the topic are permanently lost. 
+      # Returns +true+ or an exception.
+      # Deletion is eventual.
+      #
+      #  sqs.delete_queue('arn:aws:sns:us-east-1:464646271962:test') #=> true
+      # 
+    def delete_topic(topic_arn)
+      req_hash = generate_request('DeleteTopic', 'TopicArn' => topic_arn)
+      request_info(req_hash, SnsStatusParser.new(:logger => @logger))
+    rescue
+      on_exception
+    end
+    
+      # Sends a new message to a topic.  Body size is limited to 8 KB.
+      # If successful, this call returns true
+      #
+      #  sns.send_message('arn:aws:sns:us-east-1:464646271962:test', 'body', 'message 1') #=> true
+      #
+      # On failure, send_message raises an exception.
+      #
+    def send_message(topic_arn, body, subject = nil)
+      params = { 'TopicArn' => topic_arn, 'Message' => body }
+      params.merge!({ 'Subject' => subject }) unless !subject || subject.length == 0
+      req_hash = generate_post_request('Publish', params)
+      request_info(req_hash, SnsStatusParser.new(:logger => @logger))
+    rescue
+      on_exception
+    end
+
+      # Same as send_message
+    alias_method :push_message, :send_message
+
+      # Retrieves the topic attribute(s). Returns a hash of attribute(s) or an exception.
+    def get_topic_attributes(topic_arn)
+      req_hash = generate_request('GetTopicAttributes', 'TopicArn' => topic_arn)
+      request_info(req_hash, SnsGetTopicAttributesParser.new(:logger => @logger))
+    rescue
+      on_exception
+    end
+    
+      # Retrieves the topic subscribers(s). Returns a hash containing a :set of members and the :next token
+    def list_subscriptions_by_topic(topic_arn, next_token = nil)
+      params = { 'TopicArn' => topic_arn }
+      params.merge!({ 'NextToken' => next_token }) unless !next_token
+      req_hash = generate_request('ListSubscriptionsByTopic', params)
+      request_info(req_hash, SnsListSubscriptionsByTopicParser.new(:logger => @logger))
+    rescue
+      on_exception
+    end
+    
+      # Subscribe a new endpoint to a topic
+    def subscribe_to_topic(topic_arn, protocol, end_point)
+      req_hash = generate_request('Subscribe', 'TopicArn' => topic_arn, 'Protocol' => protocol, 'Endpoint' => end_point)
+      token = request_info(req_hash, SnsSubscribeParser.new(:logger => @logger))
+      if token == 'pending confirmation'
+        true
+      else
+        member               = Sns::Member.new
+        member.topic_arn     = topic_arn
+        member.token         = token
+        member.sns_interface = self
+        member
+      end
+    end
+    
+    # Add permissions to a topic.
+    #
+    #  sns.add_permissions('arn:aws:sns:us-east-1:464646271962:test',
+    #                     'testLabel', ['125074342641','125074342642'],
+    #                     ['Publish','Subscribe']) #=> true
+    #
+    #  +permissions+ is a hash of: AccountId => ActionName
+    #  (valid ActionNames: * | Publish | Subscribe | Unsubscribe | GetTopicAttributes | SetTopicAttributes | ConfirmSubscription )
+    def add_permissions(topic_arn, label, grantees, actions)
+      params = {}
+      # add each member
+      grantees.each_with_index { |awsid,i| params.merge!("AWSAccountId.member.#{i + 1}" => awsid) }
+      # add each action
+      actions.each_with_index  { |action,i| params.merge!("ActionName.member.#{i + 1}" => action) }
+      # standard params
+      params.merge!('Label'    => label,
+                    'TopicArn' => topic_arn )
+      req_hash = generate_request('AddPermission', params)
+      request_info(req_hash, SnsStatusParser.new(:logger => @logger))
+    rescue
+      on_exception
+    end
+
+    # Revoke any permissions in the topic policy that matches the +label+ parameter.
+    #
+    #  sns.remove_permissions('arn:aws:sns:us-east-1:464646271962:test',
+    #                        'testLabel') # => true
+    #
+    def remove_permissions(topic_arn, label)
+      req_hash = generate_request('RemovePermission',
+                                  'Label'    => label,
+                                  'TopicArn' => topic_arn )
+      request_info(req_hash, SnsStatusParser.new(:logger => @logger))
+    rescue
+      on_exception
+    end
+
+      # Sets a topic attribute. Returns +true+ or an exception.
+      #
+      #  sns.set_queue_attributes('arn:aws:sns:us-east-1:464646271962:test', "DisplayName", "Wendy's Widgets") #=> true
+      #
+    def set_topic_attributes(topic_arn, attribute, value)
+      req_hash = generate_request('SetTopicAttributes', 
+                                  'AttributeName'  => attribute,
+                                  'AttributeValue' => value,
+                                  'TopicArn'       => topic_arn)
+      request_info(req_hash, SnsStatusParser.new(:logger => @logger))
+    rescue
+      on_exception
+    end
+
+    #-----------------------------------------------------------------
+    #      PARSERS: Status Response Parser
+    #-----------------------------------------------------------------
+
+    class SnsStatusParser < RightAWSParser # :nodoc:
+      def tagend(name)
+        if name == 'ResponseMetadata'
+          @result = true
+        end
+      end
+    end
+
+    #-----------------------------------------------------------------
+    #      PARSERS: Queue
+    #-----------------------------------------------------------------
+
+    class SnsCreateTopicParser < RightAWSParser # :nodoc:
+      def tagend(name)
+        @result = @text if name == 'TopicArn'
+      end
+    end
+
+    class SnsListTopicsParser < RightAWSParser # :nodoc:
+      def reset
+        @result = []
+      end
+      def tagend(name)
+        @result << @text if name == 'TopicArn'
+      end
+    end
+
+    class SnsGetTopicAttributesParser < RightAWSParser # :nodoc:
+      def reset
+        @result = {}
+      end
+      def tagend(name)
+        case name 
+          when 'key'   then @current_attribute          = @text
+          when 'value' then @result[@current_attribute] = @text
+        end
+      end
+    end
+    
+    class SnsListSubscriptionsByTopicParser < RightAWSParser # :nodoc:
+      def reset
+        @result = {}
+      end
+      def tagend(name)
+        case name 
+          when 'member'    then
+            @result[:set] ||= []
+            @result[:set] <<  Sns::Member.parse(@text)
+          when 'NextToken' then @result[:next] = @text
+        end
+      end
+    end
+    
+    class SnsSubscribeParser < RightAWSParser # :nodoc:
+      def tagend(name)
+        @result = @text if name == 'SubscriptionArn'
+      end
+    end
+    
+  end
+
+end