choria-mcorpc-support 0.0.1

data/lib/mcollective/aggregate/base.rb

@@ -0,0 +1,40 @@
+module MCollective
+  class Aggregate
+    class Base
+      attr_accessor :name, :result, :output_name, :action, :aggregate_format, :arguments
+
+      def initialize(output_name, arguments, aggregate_format, action)
+        @name = self.class.to_s
+        @output_name = output_name
+
+        # Any additional arguments passed in the ddl after the output field will
+        # be stored in the arguments array which can be used in the function
+        @arguments = arguments
+        @aggregate_format = aggregate_format
+        @action = action
+        @result = {:value => nil, :type => nil, :output => output_name}
+
+        startup_hook
+      end
+
+      ['startup_hook', 'process_result'].each do |method|
+        define_method method do
+          raise RuntimeError, "'#{method}' method of function class #{@name} has not yet been implemented"
+        end
+      end
+
+      # Stops execution of the function and returns a specific ResultObject,
+      # aggregate functions will most likely override this but this is the simplest
+      # case so we might as well default to that
+      def summarize
+        raise "Result type is not set while trying to summarize aggregate function results" unless @result[:type]
+
+        result_class(@result[:type]).new(@result, @aggregate_format, @action)
+      end
+
+      def result_class(type)
+        Result.const_get("#{type.to_s.capitalize}Result")
+      end
+    end
+  end
+end

data/lib/mcollective/aggregate/result.rb

@@ -0,0 +1,9 @@
+module MCollective
+  class Aggregate
+    module Result
+      require 'mcollective/aggregate/result/base'
+      require 'mcollective/aggregate/result/numeric_result'
+      require 'mcollective/aggregate/result/collection_result'
+    end
+  end
+end

data/lib/mcollective/aggregate/result/base.rb

@@ -0,0 +1,25 @@
+module MCollective
+  class Aggregate
+    module Result
+      class Base
+        attr_accessor :result, :aggregate_format, :action
+
+        def initialize(result, aggregate_format, action)
+          raise "No aggregate_format defined in ddl or aggregate function" unless aggregate_format
+
+          @result = result
+          @aggregate_format = aggregate_format
+          @action = action
+        end
+
+        def to_s
+          raise "'to_s' method not implemented for result class '#{self.class}'"
+        end
+
+        def result_type
+          @result[:type]
+        end
+      end
+    end
+  end
+end

data/lib/mcollective/aggregate/result/collection_result.rb

@@ -0,0 +1,19 @@
+module MCollective
+  class Aggregate
+    module Result
+      class CollectionResult<Base
+        def to_s
+          return "" if @result[:value].keys.include?(nil)
+
+          result = StringIO.new
+
+          @result[:value].sort{|x,y| x[1] <=> y[1]}.reverse.each do |value|
+            result.puts @aggregate_format % [value[0], value[1]]
+          end
+
+          result.string.chomp
+        end
+      end
+    end
+  end
+end

data/lib/mcollective/aggregate/result/numeric_result.rb

@@ -0,0 +1,13 @@
+module MCollective
+  class Aggregate
+    module Result
+      class NumericResult<Base
+        def to_s
+          return "" if @result[:value].nil?
+
+          return @aggregate_format % @result[:value]
+        end
+      end
+    end
+  end
+end

data/lib/mcollective/aggregate/sum.ddl

@@ -0,0 +1,33 @@
+metadata  :name        => "Sum",
+          :description => "Determine the total added value of a set of values",
+          :author      => "Pieter Loubser <pieter.loubser@puppetlabs.com>",
+          :license     => "ASL 2.0",
+          :version     => "1.0",
+          :url         => "https://docs.puppetlabs.com/mcollective/plugin_directory/",
+          :timeout     => 5
+
+usage <<-USAGE
+
+  This aggregate plugin will determine the total added value of a set of values.
+
+  DDL Example:
+
+    summarize do
+      aggregate sum(:value)
+    end
+
+  Sample Output:
+
+    host1.example.com
+      Value: 10
+
+    host2.example.com
+      Value: 20
+
+
+   Summary of Value:
+
+      Sum of Value: 30
+
+USAGE
+

data/lib/mcollective/aggregate/sum.rb

@@ -0,0 +1,18 @@
+module MCollective
+  class Aggregate
+    class Sum<Base
+      def startup_hook
+        @result[:value] = 0
+        @result[:type] = :numeric
+
+        # Set default aggregate_function if it is undefined
+        @aggregate_format = "Sum of #{@result[:output]}: %f" unless @aggregate_format
+      end
+
+      # Determines the average of a set of numerical values
+      def process_result(value, reply)
+        @result[:value] += value
+      end
+    end
+  end
+end

data/lib/mcollective/aggregate/summary.ddl

@@ -0,0 +1,33 @@
+metadata  :name        => "summary",
+          :description => "Displays the summary of a set of results",
+          :author      => "Pieter Loubser <pieter.loubser@puppetlabs.com>",
+          :license     => "ASL 2.0",
+          :version     => "1.0",
+          :url         => "https://docs.puppetlabs.com/mcollective/plugin_directory/",
+          :timeout     => 5
+
+usage <<-USAGE
+
+  This aggregate plugin will display the summary of a set of results.
+
+  DDL Example:
+
+    summarize do
+      aggregate summary(:value)
+    end
+
+  Sample Output:
+
+    host1.example.com
+      Property: collectives
+          Value: ["mcollective", "uk_collective"]
+
+    Summary of Value:
+
+        mcollective = 25
+      uk_collective = 15
+      fr_collective = 9
+      us_collective = 1
+
+USAGE
+

data/lib/mcollective/aggregate/summary.rb

@@ -0,0 +1,53 @@
+module MCollective
+  class Aggregate
+    class Summary<Base
+      # Before function is run processing
+      def startup_hook
+        @result[:value] = {}
+        @result[:type] = :collection
+
+        # set default aggregate_format if it is undefined
+        @aggregate_format = :calculate unless @aggregate_format
+      end
+
+      # Increments the value field if value has been seen before
+      # Else create a new value field
+      def process_result(value, reply)
+        unless value.nil?
+          if value.is_a? Array
+            value.map{|val| add_value(val)}
+          else
+            add_value(value)
+          end
+        end
+      end
+
+      def add_value(value)
+        if @result[:value].keys.include?(value)
+          @result[:value][value] += 1
+        else
+          @result[:value][value] = 1
+        end
+      end
+
+      def summarize
+        if @aggregate_format == :calculate
+          max_key_length = @result[:value].keys.map do |k|
+
+            # Response values retain their types. Here we check
+            # if the response is a string and turn it into a string
+            # if it isn't one.
+            if k.respond_to?(:length)
+              k.length
+            elsif k.respond_to?(:to_s)
+              k.to_s.length
+            end
+          end.max
+          @aggregate_format = "%#{max_key_length}s = %s"
+        end
+
+        super
+      end
+    end
+  end
+end

data/lib/mcollective/application.rb

@@ -0,0 +1,365 @@
+require 'mcollective/rpc'
+
+module MCollective
+  class Application
+    include RPC
+
+    class << self
+      # Intialize a blank set of options if its the first time used
+      # else returns active options
+      def application_options
+        intialize_application_options unless @application_options
+        @application_options
+      end
+
+      # set an option in the options hash
+      def []=(option, value)
+        intialize_application_options unless @application_options
+        @application_options[option] = value
+      end
+
+      # retrieves a specific option
+      def [](option)
+        intialize_application_options unless @application_options
+        @application_options[option]
+      end
+
+      # Sets the application description, there can be only one
+      # description per application so multiple calls will just
+      # change the description
+      def description(descr)
+        self[:description] = descr
+      end
+
+      # Supplies usage information, calling multiple times will
+      # create multiple usage lines in --help output
+      def usage(usage)
+        self[:usage] << usage
+      end
+
+      def exclude_argument_sections(*sections)
+        sections = [sections].flatten
+
+        sections.each do |s|
+          raise "Unknown CLI argument section #{s}" unless ["rpc", "common", "filter"].include?(s)
+        end
+
+        intialize_application_options unless @application_options
+        self[:exclude_arg_sections] = sections
+      end
+
+      # Wrapper to create command line options
+      #
+      #  - name: varaible name that will be used to access the option value
+      #  - description: textual info shown in --help
+      #  - arguments: a list of possible arguments that can be used
+      #    to activate this option
+      #  - type: a data type that ObjectParser understand of :bool or :array
+      #  - required: true or false if this option has to be supplied
+      #  - validate: a proc that will be called with the value used to validate
+      #    the supplied value
+      #
+      #   option :foo,
+      #          :description => "The foo option"
+      #          :arguments   => ["--foo ARG"]
+      #
+      # after this the value supplied will be in configuration[:foo]
+      def option(name, arguments)
+        opt = {:name => name,
+               :description => nil,
+               :arguments => [],
+               :type => String,
+               :required => false,
+               :validate => Proc.new { true }}
+
+        arguments.each_pair{|k,v| opt[k] = v}
+
+        self[:cli_arguments] << opt
+      end
+
+      # Creates an empty set of options
+      def intialize_application_options
+        @application_options = {:description          => nil,
+                                :usage                => [],
+                                :cli_arguments        => [],
+                                :exclude_arg_sections => []}
+      end
+    end
+
+    # The application configuration built from CLI arguments
+    def configuration
+      @application_configuration ||= {}
+      @application_configuration
+    end
+
+    # The active options hash used for MC::Client and other configuration
+    def options
+      @options
+    end
+
+    # Calls the supplied block in an option for validation, an error raised
+    # will log to STDERR and exit the application
+    def validate_option(blk, name, value)
+      validation_result = blk.call(value)
+
+      unless validation_result == true
+        STDERR.puts "Validation of #{name} failed: #{validation_result}"
+        exit 1
+      end
+    end
+
+    # Creates a standard options hash, pass in a block to add extra headings etc
+    # see Optionparser
+    def clioptions(help)
+      oparser = Optionparser.new({:verbose => false, :progress_bar => true}, "filter", application_options[:exclude_arg_sections])
+
+      options = oparser.parse do |parser, options|
+        if block_given?
+          yield(parser, options)
+        end
+
+        RPC::Helpers.add_simplerpc_options(parser, options) unless application_options[:exclude_arg_sections].include?("rpc")
+      end
+
+      return oparser.parser.help if help
+
+      validate_cli_options
+
+      post_option_parser(configuration) if respond_to?(:post_option_parser)
+
+      return options
+    rescue Exception => e
+      application_failure(e)
+    end
+
+    # Builds an ObjectParser config, parse the CLI options and validates based
+    # on the option config
+    def application_parse_options(help=false)
+      @options ||= {:verbose => false}
+
+      @options = clioptions(help) do |parser, options|
+        parser.define_head application_description if application_description
+        parser.banner = ""
+
+        if application_usage
+          parser.separator ""
+
+          application_usage.each do |u|
+            parser.separator "Usage: #{u}"
+          end
+
+          parser.separator ""
+        end
+
+        parser.separator "Application Options" unless application_cli_arguments.empty?
+
+        parser.define_tail ""
+        parser.define_tail "The Marionette Collective #{MCollective.version}"
+
+
+        application_cli_arguments.each do |carg|
+          opts_array = []
+
+          opts_array << :on
+
+          # if a default is set from the application set it up front
+          if carg.include?(:default)
+            configuration[carg[:name]] = carg[:default]
+          end
+
+          # :arguments are multiple possible ones
+          if carg[:arguments].is_a?(Array)
+            carg[:arguments].each {|a| opts_array << a}
+          else
+            opts_array << carg[:arguments]
+          end
+
+          # type was given and its not one of our special types, just pass it onto optparse
+          opts_array << carg[:type] if carg[:type] && ![:boolean, :bool, :array].include?(carg[:type])
+
+          opts_array << carg[:description]
+
+          # Handle our special types else just rely on the optparser to handle the types
+          if [:bool, :boolean].include?(carg[:type])
+            parser.send(*opts_array) do |v|
+              validate_option(carg[:validate], carg[:name], v)
+
+              configuration[carg[:name]] = v
+            end
+
+          elsif carg[:type] == :array
+            parser.send(*opts_array) do |v|
+              validate_option(carg[:validate], carg[:name], v)
+
+              configuration[carg[:name]] = [] unless configuration.include?(carg[:name])
+              configuration[carg[:name]] << v
+            end
+
+          else
+            parser.send(*opts_array) do |v|
+              validate_option(carg[:validate], carg[:name], v)
+
+              configuration[carg[:name]] = v
+            end
+          end
+        end
+      end
+    end
+
+    def validate_cli_options
+      # Check all required parameters were set
+      validation_passed = true
+      application_cli_arguments.each do |carg|
+        # Check for required arguments
+        if carg[:required]
+          unless configuration[ carg[:name] ]
+            validation_passed = false
+            STDERR.puts "The #{carg[:name]} option is mandatory"
+          end
+        end
+      end
+
+      unless validation_passed
+        STDERR.puts "\nPlease run with --help for detailed help"
+        exit 1
+      end
+
+
+    end
+
+    # Retrieves the full hash of application options
+    def application_options
+      self.class.application_options
+    end
+
+    # Retrieve the current application description
+    def application_description
+      application_options[:description]
+    end
+
+    # Return the current usage text false if nothing is set
+    def application_usage
+      usage = application_options[:usage]
+
+      usage.empty? ? false : usage
+    end
+
+    # Returns an array of all the arguments built using
+    # calls to optin
+    def application_cli_arguments
+      application_options[:cli_arguments]
+    end
+
+    # Handles failure, if we're far enough in the initialization
+    # phase it will log backtraces if its in verbose mode only
+    def application_failure(e, err_dest=STDERR)
+      # peole can use exit() anywhere and not get nasty backtraces as a result
+      if e.is_a?(SystemExit)
+        disconnect
+        raise(e)
+      end
+
+      if options[:verbose]
+        err_dest.puts "\nThe %s application failed to run: %s\n" % [ Util.colorize(:bold, $0), Util.colorize(:red, e.to_s)]
+      else
+        err_dest.puts "\nThe %s application failed to run, use -v for full error backtrace details: %s\n" % [ Util.colorize(:bold, $0), Util.colorize(:red, e.to_s)]
+      end
+
+      if options.nil? || options[:verbose]
+        e.backtrace.first << Util.colorize(:red, "  <----")
+        err_dest.puts "\n%s %s" % [ Util.colorize(:red, e.to_s), Util.colorize(:bold, "(#{e.class.to_s})")]
+        e.backtrace.each{|l| err_dest.puts "\tfrom #{l}"}
+      end
+
+      disconnect
+
+      exit 1
+    end
+
+    def help
+      application_parse_options(true)
+    end
+
+    # The main logic loop, builds up the options, validate configuration and calls
+    # the main as supplied by the user.  Disconnects when done and pass any exception
+    # onto the application_failure helper
+    def run
+      application_parse_options
+
+      validate_configuration(configuration) if respond_to?(:validate_configuration)
+
+      Util.setup_windows_sleeper if Util.windows?
+
+      main
+
+      disconnect
+
+    rescue Exception => e
+      application_failure(e)
+    end
+
+    def disconnect
+      MCollective::PluginManager["connector_plugin"].disconnect
+    rescue
+    end
+
+    # Fake abstract class that logs if the user tries to use an application without
+    # supplying a main override method.
+    def main
+      STDERR.puts "Applications need to supply a 'main' method"
+      exit 1
+    end
+
+    def halt_code(stats)
+      request_stats = {:discoverytime => 0,
+                       :discovered => 0,
+                       :okcount => 0,
+                       :failcount => 0}.merge(stats.to_hash)
+
+      if (request_stats[:discoverytime] == 0 && request_stats[:responses] == 0)
+        return 4
+      end
+
+      if (request_stats[:discovered] > 0)
+        if (request_stats[:responses] == 0)
+          return 3
+        elsif (request_stats[:failcount] > 0)
+          return 2
+        end
+      end
+
+      if (request_stats[:discovered] == 0)
+        if (request_stats[:responses] && request_stats[:responses] > 0)
+          return 0
+        else
+          return 1
+        end
+      end
+
+      return 0
+    end
+
+    # A helper that creates a consistent exit code for applications by looking at an
+    # instance of MCollective::RPC::Stats
+    #
+    # Exit with 0 if nodes were discovered and all passed
+    # Exit with 0 if no discovery were done and > 0 responses were received, all ok
+    # Exit with 1 if no nodes were discovered
+    # Exit with 2 if nodes were discovered but some RPC requests failed
+    # Exit with 3 if nodes were discovered, but no responses received
+    # Exit with 4 if no discovery were done and no responses were received
+    def halt(stats)
+      exit(halt_code(stats))
+    end
+
+    # Wrapper around MC::RPC#rpcclient that forcably supplies our options hash
+    # if someone forgets to pass in options in an application the filters and other
+    # cli options wouldnt take effect which could have a disasterous outcome
+    def rpcclient(agent, flags = {})
+      flags[:options] = options unless flags.include?(:options)
+      flags[:exit_on_failure] = false
+
+      super
+    end
+  end
+end