chef-handler-sns 1.2.0 → 2.0.0

data/lib/chef/handler/sns.rb

@@ -1,5 +1,6 @@
 #
-# Author:: Xabier de Zuazo (<xabier@onddo.com>)
+# Author:: Xabier de Zuazo (<xabier@zuazo.org>)
+# Copyright:: Copyright (c) 2015 Xabier de Zuazo
 # Copyright:: Copyright (c) 2014 Onddo Labs, SL.
 # License:: Apache License, Version 2.0
 #
@@ -22,76 +23,284 @@ require 'aws-sdk'
 require 'erubis'
 
 class Chef
+  #
+  # Chef report handlers.
+  #
   class Handler
+    #
+    # Chef Handler SNS main class.
+    #
+    # A simple Chef report handler that reports status of a Chef run through
+    # [Amazon SNS](http://aws.amazon.com/sns/),
+    # [including IAM roles support](#usage-with-amazon-iam-roles).
+    #
     class Sns < ::Chef::Handler
+      #
+      # Include {Config.config_init} and {Config.config_check} methods.
+      #
       include ::Chef::Handler::Sns::Config
 
-      def initialize(config={})
-        Chef::Log.debug("#{self.class.to_s} initialized.")
+      #
+      # Constructs a new `Sns` object.
+      #
+      # @example `/etc/chef/client.rb` Configuration Example
+      #   require 'chef/handler/sns'
+      #   sns_handler = Chef::Handler::Sns.new
+      #   sns_handler.access_key '***AMAZON-KEY***'
+      #   sns_handler.secret_key '***AMAZON-SECRET***'
+      #   sns_handler.topic_arn 'arn:aws:sns:***'
+      #   sns_handler.region 'us-east-1' # optional
+      #   exception_handlers << sns_handler
+      #
+      # @example `/etc/chef/client.rb` Example Using a Hash for Configuration
+      #   require 'chef/handler/sns'
+      #   exception_handlers << Chef::Handler::Sns.new(
+      #     access_key: '***AMAZON-KEY***',
+      #     secret_key: '***AMAZON-SECRET***',
+      #     topic_arn: 'arn:aws:sns:***',
+      #     region: 'us-east-1' # optional
+      #   )
+      #
+      # @example `/etc/chef/client.rb` Using IAM Roles
+      #   require 'chef/handler/sns'
+      #   exception_handlers << Chef::Handler::Sns.new(
+      #     topic_arn: 'arn:aws:sns:us-east-1:12341234:MyTopicName'
+      #   )
+      #
+      #
+      # @example Using the `chef_handler` Cookbook
+      #   # Install the `chef-handler-sns` RubyGem during the compile phase
+      #   chef_gem 'chef-handler-sns' do
+      #     compile_time true # Only for Chef 12
+      #   end
+      #   # Then activate the handler with the `chef_handler` LWRP
+      #   chef_handler 'Chef::Handler::Sns' do
+      #     source 'chef/handler/sns'
+      #     arguments(
+      #       access_key: '***AMAZON-KEY***',
+      #       secret_key: '***AMAZON-SECRET***',
+      #       topic_arn: 'arn:aws:sns:***'
+      #     )
+      #     supports exception: true
+      #     action :enable
+      #   end
+      #
+      # @example Using the `chef-client` Cookbook
+      #   node.default['chef_client']['config']['exception_handlers'] = [{
+      #     'class' => 'Chef::Handler::Sns',
+      #     'arguments' => {
+      #       access_key: '***AMAZON-KEY***',
+      #       secret_key: '***AMAZON-SECRET***',
+      #       topic_arn: 'arn:aws:sns:***'
+      #     }.map { |k, v| "#{k}: #{v.inspect}" }
+      #   }]
+      #
+      # @param config [Hash] Configuration options.
+      #
+      # @option config [String] :access_key AWS access key (required, but will
+      #   try to read it from Ohai with IAM roles).
+      # @option config [String] :secret_key AWS secret key (required, but will
+      #   try to read it from Ohai with IAM roles).
+      # @option config [String] :token AWS security token (optional, read from
+      #   Ohai with IAM roles). Set to `false` to disable the token detected by
+      #   Ohai.
+      # @option config [String] :topic_arn AWS topic ARN name (required).
+      # @option config [String] :region AWS region (optional).
+      # @option config [String] :subject Message subject string in erubis
+      #   format (optional).
+      # @option config [String] :body_template Full path of an erubis template
+      #   file to use for the message body (optional).
+      # @option config [Array] :filter_opsworks_activities An array of
+      #   OpsWorks activities to be triggered with (optional). When set,
+      #   everything else will be discarded.
+      #
+      # @api public
+      #
+      def initialize(config = {})
+        Chef::Log.debug("#{self.class} initialized.")
         config_init(config)
       end
 
+      #
+      # Send a SNS report message.
+      #
+      # This is called by Chef internally.
+      #
+      # @return void
+      #
+      # @api public
+      #
       def report
         config_check(node)
-        if allow_publish(node)
-          sns.topics[topic_arn].publish(
-            sns_body,
-            { :subject => sns_subject }
-          )
-        end
-      end
-
-      def get_region
-        sns.config.region
+        return unless allow_publish(node)
+        sns.publish(
+          topic_arn: topic_arn,
+          message: sns_body,
+          subject: sns_subject
+        )
       end
 
       protected
 
+      #
+      # Checks if the message will be published based in configured OpsWorks
+      # activities.
+      #
+      # @param node [Chef::Node] Chef Node that contains the activities.
+      #
+      # @return [Boolean] Whether the message needs to be sent.
+      #
+      # @api private
+      #
       def allow_publish(node)
-        if filter_opsworks_activity.nil?
-          return true
-        end
+        return true if filter_opsworks_activity.nil?
 
-        if node.attribute?('opsworks') && node['opsworks'].attribute?('activity')
+        if node.attribute?('opsworks') &&
+           node['opsworks'].attribute?('activity')
           return filter_opsworks_activity.include?(node['opsworks']['activity'])
         end
 
-        Chef::Log.debug('You supplied opsworks activity filters, but node attr was not found. Returning false')
-        return false
+        Chef::Log.debug(
+          'You supplied opsworks activity filters, but node attr was not '\
+          'found. Returning false'
+        )
+        false
       end
 
+      #
+      # Returns the {Aws::SNS} object used to send the messages.
+      #
+      # @return [Aws::SNS::Client] The SNS client.
       def sns
         @sns ||= begin
           params = {
-            :access_key_id => access_key,
-            :secret_access_key => secret_key,
-            :logger => Chef::Log
+            access_key_id: access_key,
+            secret_access_key: secret_key,
+            logger: Chef::Log
           }
           params[:region] = region if region
           params[:session_token] = token if token
-          AWS::SNS.new(params)
+          Aws::SNS::Client.new(params)
         end
       end
 
-      def sns_subject
-        if subject
-          context = self
-          eruby = Erubis::Eruby.new(subject)
-          eruby.evaluate(context)
-        else
-          chef_client = Chef::Config[:solo] ? 'Chef Solo' : 'Chef Client'
-          status = run_status.success? ? 'success' : 'failure'
-          "#{chef_client} #{status} in #{node.name}"
+      #
+      # Fixes or forces the correct encoding of strings.
+      #
+      # Replaces wrong characters with `'?'`s.
+      #
+      # @param o [String, Object] The string to fix.
+      # @param encoding [String] The encoding to use.
+      #
+      # @return [String] The message fixed.
+      #
+      # @api private
+      #
+      def fix_encoding(o, encoding)
+        encode_opts = { invalid: :replace, undef: :replace, replace: '?' }
+
+        return o.to_s.encode(encoding, encode_opts) if RUBY_VERSION >= '2.1.0'
+        # Fix ArgumentError: invalid byte sequence in UTF-8 (issue #7)
+        o.to_s.encode(encoding, 'binary', encode_opts)
+      end
+
+      #
+      # Fixes the encoding of SNS subjects.
+      #
+      # @param o [String, Object] The subject to fix.
+      #
+      # @return [String] The message fixed.
+      #
+      # @api private
+      #
+      def fix_subject_encoding(o)
+        fix_encoding(o, 'ASCII')
+      end
+
+      #
+      # Fixes the encoding of SNS bodies.
+      #
+      # @param o [String, Object] The body to fix.
+      #
+      # @return [String] The message fixed.
+      #
+      # @api private
+      #
+      def fix_body_encoding(o)
+        fix_encoding(o, 'UTF-8')
+      end
+
+      #
+      # Returns the SNS subject used by default.
+      #
+      # @return [String] The SNS subject.
+      #
+      # @api private
+      #
+      def default_sns_subject
+        chef_client = Chef::Config[:solo] ? 'Chef Solo' : 'Chef Client'
+        status = run_status.success? ? 'success' : 'failure'
+        fix_subject_encoding("#{chef_client} #{status} in #{node.name}"[0..99])
+      end
+
+      #
+      # Limits the size of a UTF-8 string in bytes without breaking it.
+      #
+      # Based on http://stackoverflow.com/questions/12536080/
+      # ruby-limiting-a-utf-8-string-by-byte-length
+      #
+      # @param str [String] The string to limit.
+      # @param size [Fixnum] The string size in bytes.
+      #
+      # @return [String] The final string.
+      #
+      # @note This code does not work properly on Ruby `< 2.1`.
+      #
+      # @api private
+      #
+      def limit_utf8_size(str, size)
+        # Start with a string of the correct byte size, but with a possibly
+        # incomplete char at the end.
+        new_str = str.byteslice(0, size)
+
+        # We need to force_encoding from utf-8 to utf-8 so ruby will
+        # re-validate (idea from halfelf).
+        until new_str[-1].force_encoding('utf-8').valid_encoding?
+          # Remove the invalid char
+          new_str = new_str.slice(0..-2)
         end
+        new_str
       end
 
-      def sns_body
-        template = IO.read(body_template || "#{File.dirname(__FILE__)}/sns/templates/body.erb")
+      #
+      # Generates the SNS subject.
+      #
+      # @return [String] The subject string.
+      #
+      # @api private
+      #
+      def sns_subject
+        return default_sns_subject unless subject
         context = self
-        eruby = Erubis::Eruby.new(template)
-        eruby.evaluate(context)
+        eruby = Erubis::Eruby.new(fix_subject_encoding(subject))
+        fix_subject_encoding(eruby.evaluate(context))[0..99]
       end
 
+      #
+      # Generates the SNS body.
+      #
+      # @return [String] The body string.
+      #
+      # @api private
+      #
+      def sns_body
+        template = IO.read(body_template ||
+          "#{File.dirname(__FILE__)}/sns/templates/body.erb")
+        context = self
+        eruby = Erubis::Eruby.new(fix_body_encoding(template))
+        body = fix_body_encoding(eruby.evaluate(context))
+        limit_utf8_size(body, 262_144)
+      end
     end
   end
 end

data/lib/chef/handler/sns/config.rb

@@ -1,5 +1,6 @@
 #
-# Author:: Xabier de Zuazo (<xabier@onddo.com>)
+# Author:: Xabier de Zuazo (<xabier@zuazo.org>)
+# Copyright:: Copyright (c) 2015 Xabier de Zuazo
 # Copyright:: Copyright (c) 2014 Onddo Labs, SL.
 # License:: Apache License, Version 2.0
 #
@@ -23,111 +24,242 @@ require 'chef/exceptions'
 class Chef
   class Handler
     class Sns < ::Chef::Handler
+      #
+      # Reads Chef Handler SNS configuration options or calculate them if not
+      # set.
+      #
       module Config
-        Config.extend Config # let Config use the methods it contains as instance methods
+        #
+        # Let Config use the methods it contains as instance methods:
+        #
+        Config.extend Config
+
+        #
+        # Include `#set_or_return` code.
+        #
         include ::Chef::Mixin::ParamsValidate
 
-        REQUIRED = [ 'access_key', 'secret_key', 'topic_arn' ]
+        #
+        # Required configuration options.
+        #
+        REQUIRED = %w(access_key secret_key topic_arn)
 
+        #
+        # Reads some configuration options from Ohai information.
+        #
+        # Called from {.config_check}.
+        #
+        # @param node [Chef::Node] No objects to read the information from.
+        #
+        # @return void
+        #
+        # @api private
+        #
         def config_from_ohai(node)
           config_ohai = Config::Ohai.new(node)
           [
-            :region,
             :access_key,
             :secret_key,
-            :token,
+            :token
           ].each do |attr|
-            self.send(attr, config_ohai.send(attr)) if self.send(attr).nil?
+            send(attr, config_ohai.send(attr)) if send(attr).nil?
           end
         end
 
-        def config_init(config={})
+        #
+        # Sets configuration reading it from a Hash.
+        #
+        # @param config [Hash] Configuration options to set.
+        #
+        # @return void
+        #
+        # @see Sns.initialize
+        #
+        # @api public
+        #
+        def config_init(config = {})
           config.each do |key, value|
-            if Config.respond_to?(key) and not /^config_/ =~ key.to_s
-              self.send(key, value)
+            if Config.respond_to?(key) && !key.to_s.match(/^config_/)
+              send(key, value)
             else
-              Chef::Log.warn("#{self.class.to_s}: configuration method not found: #{key}.")
+              Chef::Log.warn(
+                "#{self.class}: configuration method not found: #{key}."
+              )
             end
           end
         end
 
-        def config_check(node=nil)
+        #
+        # Checks if any required configuration option is not set.
+        #
+        # Tries to read some configuration options from Ohai before checking
+        # them.
+        #
+        # @param node [Chef::Node] Node to read Ohai information from.
+        #
+        # @return void
+        #
+        # @raise [Exceptions::ValidationFailed] When any required configuration
+        #   option is not set.
+        #
+        # @api public
+        #
+        def config_check(node = nil)
           config_from_ohai(node) if node
           REQUIRED.each do |key|
-            if self.send(key).nil?
-              raise Exceptions::ValidationFailed,
-                "Required argument #{key.to_s} is missing!"
-            end
+            next unless send(key).nil?
+            fail Exceptions::ValidationFailed,
+                 "Required argument #{key} is missing!"
           end
 
-          if body_template and not ::File.exists?(body_template)
-            raise Exceptions::ValidationFailed,
-              "Template file not found: #{body_template}."
-          end
+          return unless body_template && !::File.exist?(body_template)
+          fail Exceptions::ValidationFailed,
+               "Template file not found: #{body_template}."
         end
 
-        def access_key(arg=nil)
+        #
+        # Gets or sets AWS access key.
+        #
+        # @param arg [String] Access key.
+        #
+        # @return [String] Access Key.
+        #
+        # @api public
+        #
+        def access_key(arg = nil)
           set_or_return(
             :access_key,
             arg,
-            :kind_of => String
+            kind_of: String
           )
         end
 
-        def secret_key(arg=nil)
+        #
+        # Gets or sets AWS secret key.
+        #
+        # @param arg [String] Secret key.
+        #
+        # @return [String] Secret Key.
+        #
+        # @api public
+        #
+        def secret_key(arg = nil)
           set_or_return(
             :secret_key,
             arg,
-            :kind_of => String
+            kind_of: String
           )
         end
 
-        def region(arg=nil)
+        #
+        # Gets or sets AWS region.
+        #
+        # @param arg [String] Region.
+        #
+        # @return [String] Region.
+        #
+        # @api public
+        #
+        def region(arg = nil)
           set_or_return(
             :region,
             arg,
-            :kind_of => String
+            kind_of: String
           )
         end
 
-        def token(arg=nil)
+        #
+        # Gets or sets AWS token.
+        #
+        # @param arg [String] Token.
+        #
+        # @return [String] Token.
+        #
+        # @api public
+        #
+        def token(arg = nil)
           set_or_return(
             :token,
             arg,
-            :kind_of => [ String, FalseClass ]
+            kind_of: [String, FalseClass]
           )
         end
 
-        def topic_arn(arg=nil)
+        #
+        # Gets or sets AWS Topic ARN.
+        #
+        # It also tries to set the AWS region reading it from the ARN string.
+        #
+        # @param arg [String] Topic ARN.
+        #
+        # @return [String] Topic ARN.
+        #
+        # @api public
+        #
+        def topic_arn(arg = nil)
           set_or_return(
             :topic_arn,
             arg,
-            :kind_of => String
-          )
+            kind_of: String
+          ).tap do |arn|
+            # Get the region from the ARN:
+            next if arn.nil? || !region.nil?
+            region(arn.split(':', 5)[3])
+          end
         end
 
-        def subject(arg=nil)
+        #
+        # Gets or sets SNS message subject.
+        #
+        # @param arg [String] SNS subject.
+        #
+        # @return [String] SNS subject.
+        #
+        # @api public
+        #
+        def subject(arg = nil)
           set_or_return(
             :subject,
             arg,
-            :kind_of => String
+            kind_of: String
           )
         end
 
-        def body_template(arg=nil)
+        #
+        # Gets or sets SNS message body template file path.
+        #
+        # @param arg [String] SNS body template.
+        #
+        # @return [String] SNS body template.
+        #
+        # @api public
+        #
+        def body_template(arg = nil)
           set_or_return(
             :body_template,
             arg,
-            :kind_of => String
+            kind_of: String
           )
         end
 
-        def filter_opsworks_activity(arg=nil)
+        #
+        # Gets or sets [OpsWorks](https://aws.amazon.com/opsworks/) activities.
+        #
+        # Notifications will only be triggered for the activities in the array,
+        # everything else will be discarded.
+        #
+        # @param arg [Array] Activities list.
+        #
+        # @return [Array] Activities list.
+        #
+        # @api public
+        #
+        def filter_opsworks_activity(arg = nil)
           arg = Array(arg) if arg.is_a? String
           set_or_return(
             :filter_opsworks_activity,
             arg,
-            :kind_of => Array
+            kind_of: Array
           )
         end
       end