mcollective-client 1.3.3

data/lib/mcollective/rpc/ddl.rb

@@ -0,0 +1,258 @@
+module MCollective
+  module RPC
+    # A class that helps creating data description language files
+    # for agents.  You can define meta data, actions, input and output
+    # describing the behavior of your agent.
+    #
+    # Later you can access this information to assist with creating
+    # of user interfaces or online help
+    #
+    # A sample DDL can be seen below, you'd put this in your agent
+    # dir as <agent name>.ddl
+    #
+    #    metadata :name        => "SimpleRPC Service Agent",
+    #             :description => "Agent to manage services using the Puppet service provider",
+    #             :author      => "R.I.Pienaar",
+    #             :license     => "GPLv2",
+    #             :version     => "1.1",
+    #             :url         => "http://mcollective-plugins.googlecode.com/",
+    #             :timeout     => 60
+    #
+    #    action "status", :description => "Gets the status of a service" do
+    #       display :always
+    #
+    #       input "service",
+    #             :prompt      => "Service Name",
+    #             :description => "The service to get the status for",
+    #             :type        => :string,
+    #             :validation  => '^[a-zA-Z\-_\d]+$',
+    #             :optional    => true,
+    #             :maxlength   => 30
+    #
+    #       output "status",
+    #             :description => "The status of service",
+    #             :display_as  => "Service Status"
+    #   end
+    class DDL
+      attr_reader :meta
+
+      def initialize(agent, loadddl=true)
+        @actions = {}
+        @meta = {}
+        @config = MCollective::Config.instance
+        @agent = agent
+
+        if loadddl
+          if ddlfile = findddlfile(agent)
+            instance_eval(File.read(ddlfile))
+          else
+            raise("Can't find DDL for agent '#{agent}'")
+          end
+        end
+      end
+
+      def findddlfile(agent)
+        @config.libdir.each do |libdir|
+          ddlfile = File.join([libdir, "mcollective", "agent", "#{agent}.ddl"])
+
+          if File.exist?(ddlfile)
+            Log.debug("Found #{agent} ddl at #{ddlfile}")
+            return ddlfile
+          end
+        end
+        return false
+      end
+
+      # Registers meta data for the introspection hash
+      def metadata(meta)
+        [:name, :description, :author, :license, :version, :url, :timeout].each do |arg|
+          raise "Metadata needs a :#{arg}" unless meta.include?(arg)
+        end
+
+        @meta = meta
+      end
+
+      # Creates the definition for an action, you can nest input definitions inside the
+      # action to attach inputs and validation to the actions
+      #
+      #    action "status", :description => "Restarts a Service" do
+      #       display :always
+      #
+      #       input "service",
+      #            :prompt      => "Service Action",
+      #            :description => "The action to perform",
+      #            :type        => :list,
+      #            :optional    => true,
+      #            :list        => ["start", "stop", "restart", "status"]
+      #
+      #       output "status"
+      #            :description => "The status of the service after the action"
+      #
+      #    end
+      def action(name, input, &block)
+        raise "Action needs a :description" unless input.include?(:description)
+
+        unless @actions.include?(name)
+          @actions[name] = {}
+          @actions[name][:action] = name
+          @actions[name][:input] = {}
+          @actions[name][:output] = {}
+          @actions[name][:display] = :failed
+          @actions[name][:description] = input[:description]
+        end
+
+        # if a block is passed it might be creating input methods, call it
+        # we set @current_action so the input block can know what its talking
+        # to, this is probably an epic hack, need to improve.
+        @current_action = name
+        block.call if block_given?
+        @current_action = nil
+      end
+
+      # Registers an input argument for a given action
+      #
+      # See the documentation for action for how to use this
+      def input(argument, properties)
+        raise "Cannot figure out what action input #{argument} belongs to" unless @current_action
+
+        action = @current_action
+
+        [:prompt, :description, :type, :optional].each do |arg|
+          raise "Input needs a :#{arg}" unless properties.include?(arg)
+        end
+
+        @actions[action][:input][argument] = {:prompt => properties[:prompt],
+                                              :description => properties[:description],
+                                              :type => properties[:type],
+                                              :optional => properties[:optional]}
+
+        case properties[:type]
+          when :string
+            raise "Input type :string needs a :validation argument" unless properties.include?(:validation)
+            raise "Input type :string needs a :maxlength argument" unless properties.include?(:maxlength)
+
+            @actions[action][:input][argument][:validation] = properties[:validation]
+            @actions[action][:input][argument][:maxlength] = properties[:maxlength]
+
+          when :list
+            raise "Input type :list needs a :list argument" unless properties.include?(:list)
+
+            @actions[action][:input][argument][:list] = properties[:list]
+        end
+      end
+
+      # Registers an output argument for a given action
+      #
+      # See the documentation for action for how to use this
+      def output(argument, properties)
+        raise "Cannot figure out what action input #{argument} belongs to" unless @current_action
+        raise "Output #{argument} needs a description argument" unless properties.include?(:description)
+        raise "Output #{argument} needs a display_as argument" unless properties.include?(:display_as)
+
+        action = @current_action
+
+        @actions[action][:output][argument] = {:description => properties[:description],
+                                               :display_as  => properties[:display_as]}
+      end
+
+      # Sets the display preference to either :ok, :failed, :flatten or :always
+      # operates on action level
+      def display(pref)
+        # defaults to old behavior, complain if its supplied and invalid
+        unless [:ok, :failed, :flatten, :always].include?(pref)
+          raise "Display preference #{pref} is not valid, should be :ok, :failed, :flatten or :always"
+        end
+
+        action = @current_action
+        @actions[action][:display] = pref
+      end
+
+      # Generates help using the template based on the data
+      # created with metadata and input
+      def help(template)
+        template = IO.read(template)
+        meta = @meta
+        actions = @actions
+
+        erb = ERB.new(template, 0, '%')
+        erb.result(binding)
+      end
+
+      # Returns an array of actions this agent support
+      def actions
+        @actions.keys
+      end
+
+      # Returns the interface for a specific action
+      def action_interface(name)
+        @actions[name] || {}
+      end
+
+      # Helper to use the DDL to figure out if the remote call should be
+      # allowed based on action name and inputs.
+      def validate_request(action, arguments)
+        # is the action known?
+        unless actions.include?(action)
+          raise DDLValidationError, "Attempted to call action #{action} for #{@agent} but it's not declared in the DDL"
+        end
+
+        input = action_interface(action)[:input]
+
+        input.keys.each do |key|
+          unless input[key][:optional]
+            unless arguments.keys.include?(key)
+              raise DDLValidationError, "Action #{action} needs a #{key} argument"
+            end
+          end
+
+          # validate strings, lists and booleans, we'll add more types of validators when
+          # all the use cases are clear
+          #
+          # only does validation for arguments actually given, since some might
+          # be optional.  We validate the presense of the argument earlier so
+          # this is a safe assumption, just to skip them.
+          #
+          # :string can have maxlength and regex.  A maxlength of 0 will bypasss checks
+          # :list has a array of valid values
+          if arguments.keys.include?(key)
+            case input[key][:type]
+              when :string
+                raise DDLValidationError, "Input #{key} should be a string" unless arguments[key].is_a?(String)
+
+                if input[key][:maxlength].to_i > 0
+                  if arguments[key].size > input[key][:maxlength].to_i
+                    raise DDLValidationError, "Input #{key} is longer than #{input[key][:maxlength]} character(s)"
+                  end
+                end
+
+                unless arguments[key].match(Regexp.new(input[key][:validation]))
+                  raise DDLValidationError, "Input #{key} does not match validation regex #{input[key][:validation]}"
+                end
+
+              when :list
+                unless input[key][:list].include?(arguments[key])
+                  raise DDLValidationError, "Input #{key} doesn't match list #{input[key][:list].join(', ')}"
+                end
+
+              when :boolean
+                unless [TrueClass, FalseClass].include?(arguments[key].class)
+                  raise DDLValidationError, "Input #{key} should be a boolean"
+                end
+
+              when :integer
+                raise DDLValidationError, "Input #{key} should be a integer" unless arguments[key].is_a?(Fixnum)
+
+              when :float
+                raise DDLValidationError, "Input #{key} should be a floating point number" unless arguments[key].is_a?(Float)
+
+              when :number
+                raise DDLValidationError, "Input #{key} should be a number" unless arguments[key].is_a?(Numeric)
+            end
+          end
+        end
+
+        true
+      end
+    end
+  end
+end

data/lib/mcollective/rpc/helpers.rb

@@ -0,0 +1,339 @@
+module MCollective
+  module RPC
+    # Various utilities for the RPC system
+    class Helpers
+      # Checks in PATH returns true if the command is found
+      def self.command_in_path?(command)
+        found = ENV["PATH"].split(File::PATH_SEPARATOR).map do |p|
+          File.exist?(File.join(p, command))
+        end
+
+        found.include?(true)
+      end
+
+      # Parse JSON output as produced by printrpc and extract
+      # the "sender" of each rpc response
+      #
+      # The simplist valid JSON based data would be:
+      #
+      # [
+      #  {"sender" => "example.com"},
+      #  {"sender" => "another.com"}
+      # ]
+      def self.extract_hosts_from_json(json)
+        hosts = JSON.parse(json)
+
+        raise "JSON hosts list is not an array" unless hosts.is_a?(Array)
+
+        hosts.map do |host|
+          raise "JSON host list is not an array of Hashes" unless host.is_a?(Hash)
+          raise "JSON host list does not have senders in it" unless host.include?("sender")
+
+          host["sender"]
+        end.uniq
+      end
+
+      # Given an array of something, make sure each is a string
+      # chomp off any new lines and return just the array of hosts
+      def self.extract_hosts_from_array(hosts)
+        [hosts].flatten.map do |host|
+          raise "#{host} should be a string" unless host.is_a?(String)
+          host.chomp
+        end
+      end
+
+      # Figures out the columns and liens of the current tty
+      #
+      # Returns [0, 0] if it can't figure it out or if you're
+      # not running on a tty
+      def self.terminal_dimensions
+        return [0, 0] unless STDOUT.tty?
+
+        return [80, 40] if Util.windows?
+
+        if ENV["COLUMNS"] && ENV["LINES"]
+          return [ENV["COLUMNS"].to_i, ENV["LINES"].to_i]
+
+        elsif ENV["TERM"] && command_in_path?("tput")
+          return [`tput cols`.to_i, `tput lines`.to_i]
+
+        elsif command_in_path?('stty')
+          return `stty size`.scan(/\d+/).map {|s| s.to_i }
+        else
+          return [0, 0]
+        end
+      rescue
+        [0, 0]
+      end
+
+      # Return color codes, if the config color= option is false
+      # just return a empty string
+      def self.color(code)
+        colorize = Config.instance.color
+
+        colors = {:red => "",
+          :green => "",
+          :yellow => "",
+          :cyan => "",
+          :bold => "",
+          :reset => ""}
+
+        if colorize
+          return colors[code] || ""
+        else
+          return ""
+        end
+      end
+
+      # Helper to return a string in specific color
+      def self.colorize(code, msg)
+        "#{self.color(code)}#{msg}#{self.color(:reset)}"
+      end
+
+      # Returns a blob of text representing the results in a standard way
+      #
+      # It tries hard to do sane things so you often
+      # should not need to write your own display functions
+      #
+      # If the agent you are getting results for has a DDL
+      # it will use the hints in there to do the right thing specifically
+      # it will look at the values of display in the DDL to choose
+      # when to show results
+      #
+      # If you do not have a DDL you can pass these flags:
+      #
+      #    printrpc exim.mailq, :flatten => true
+      #    printrpc exim.mailq, :verbose => true
+      #
+      # If you've asked it to flatten the result it will not print sender
+      # hostnames, it will just print the result as if it's one huge result,
+      # handy for things like showing a combined mailq.
+      def self.rpcresults(result, flags = {})
+        flags = {:verbose => false, :flatten => false, :format => :console}.merge(flags)
+
+        result_text = ""
+        ddl = nil
+
+        # if running in verbose mode, just use the old style print
+        # no need for all the DDL helpers obfuscating the result
+        if flags[:format] == :json
+          if STDOUT.tty?
+            result_text = JSON.pretty_generate(result)
+          else
+            result_text = result.to_json
+          end
+        else
+          if flags[:verbose]
+            result_text = old_rpcresults(result, flags)
+          else
+            [result].flatten.each do |r|
+              begin
+                ddl ||= DDL.new(r.agent).action_interface(r.action.to_s)
+
+                sender = r[:sender]
+                status = r[:statuscode]
+                message = r[:statusmsg]
+                display = ddl[:display]
+                result = r[:data]
+
+                # appand the results only according to what the DDL says
+                case display
+                when :ok
+                  if status == 0
+                    result_text << text_for_result(sender, status, message, result, ddl)
+                  end
+
+                when :failed
+                  if status > 0
+                    result_text << text_for_result(sender, status, message, result, ddl)
+                  end
+
+                when :always
+                  result_text << text_for_result(sender, status, message, result, ddl)
+
+                when :flatten
+                  result_text << text_for_flattened_result(status, result)
+
+                end
+              rescue Exception => e
+                # no DDL so just do the old style print unchanged for
+                # backward compat
+                result_text = old_rpcresults(result, flags)
+              end
+            end
+          end
+        end
+
+        result_text
+      end
+
+      # Return text representing a result
+      def self.text_for_result(sender, status, msg, result, ddl)
+        statusses = ["",
+                     colorize(:red, "Request Aborted"),
+                     colorize(:yellow, "Unknown Action"),
+                     colorize(:yellow, "Missing Request Data"),
+                     colorize(:yellow, "Invalid Request Data"),
+                     colorize(:red, "Unknown Request Status")]
+
+        result_text = "%-40s %s\n" % [sender, statusses[status]]
+        result_text << "   %s\n" % [colorize(:yellow, msg)] unless msg == "OK"
+
+        # only print good data, ignore data that results from failure
+        if [0, 1].include?(status)
+          if result.is_a?(Hash)
+            # figure out the lengths of the display as strings, we'll use
+            # it later to correctly justify the output
+            lengths = result.keys.map do |k|
+              begin
+                ddl[:output][k][:display_as].size
+              rescue
+                k.to_s.size
+              end
+            end
+
+            result.keys.each do |k|
+              # get all the output fields nicely lined up with a
+              # 3 space front padding
+              begin
+                display_as = ddl[:output][k][:display_as]
+              rescue
+                display_as = k.to_s
+              end
+
+              display_length = display_as.size
+              padding = lengths.max - display_length + 3
+              result_text << " " * padding
+
+              result_text << "#{display_as}:"
+
+              if [String, Numeric].include?(result[k].class)
+                lines = result[k].to_s.split("\n")
+
+                if lines.empty?
+                  result_text << "\n"
+                else
+                  lines.each_with_index do |line, i|
+                    i == 0 ? padtxt = " " : padtxt = " " * (padding + display_length + 2)
+
+                    result_text << "#{padtxt}#{line}\n"
+                  end
+                end
+              else
+                padding = " " * (lengths.max + 5)
+                result_text << " " << result[k].pretty_inspect.split("\n").join("\n" << padding) << "\n"
+              end
+            end
+          else
+            result_text << "\n\t" + result.pretty_inspect.split("\n").join("\n\t")
+          end
+        end
+
+        result_text << "\n"
+        result_text
+      end
+
+      # Returns text representing a flattened result of only good data
+      def self.text_for_flattened_result(status, result)
+        result_text = ""
+
+        if status <= 1
+          unless result.is_a?(String)
+            result_text << result.pretty_inspect
+          else
+            result_text << result
+          end
+        end
+      end
+
+      # Backward compatible display block for results without a DDL
+      def self.old_rpcresults(result, flags = {})
+        result_text = ""
+
+        if flags[:flatten]
+          result.each do |r|
+            if r[:statuscode] <= 1
+              data = r[:data]
+
+              unless data.is_a?(String)
+                result_text << data.pretty_inspect
+              else
+                result_text << data
+              end
+            else
+              result_text << r.pretty_inspect
+            end
+          end
+
+          result_text << ""
+        else
+          [result].flatten.each do |r|
+
+            if flags[:verbose]
+              result_text << "%-40s: %s\n" % [r[:sender], r[:statusmsg]]
+
+              if r[:statuscode] <= 1
+                r[:data].pretty_inspect.split("\n").each {|m| result_text += "    #{m}"}
+                result_text << "\n\n"
+              elsif r[:statuscode] == 2
+                # dont print anything, no useful data to display
+                # past what was already shown
+              elsif r[:statuscode] == 3
+                # dont print anything, no useful data to display
+                # past what was already shown
+              elsif r[:statuscode] == 4
+                # dont print anything, no useful data to display
+                # past what was already shown
+              else
+                result_text << "    #{r[:statusmsg]}"
+              end
+            else
+              unless r[:statuscode] == 0
+                result_text << "%-40s %s\n" % [r[:sender], colorize(:red, r[:statusmsg])]
+              end
+            end
+          end
+        end
+
+        result_text << ""
+      end
+
+      # Add SimpleRPC common options
+      def self.add_simplerpc_options(parser, options)
+        parser.separator ""
+
+        # add SimpleRPC specific options to all clients that use our library
+        parser.on('--np', '--no-progress', 'Do not show the progress bar') do |v|
+          options[:progress_bar] = false
+        end
+
+        parser.on('--one', '-1', 'Send request to only one discovered nodes') do |v|
+          options[:mcollective_limit_targets] = 1
+        end
+
+        parser.on('--batch SIZE', Integer, 'Do requests in batches') do |v|
+          options[:batch_size] = v
+        end
+
+        parser.on('--batch-sleep SECONDS', Float, 'Sleep time between batches') do |v|
+          options[:batch_sleep_time] = v
+        end
+
+        parser.on('--limit-nodes COUNT', '--ln', 'Send request to only a subset of nodes, can be a percentage') do |v|
+          raise "Invalid limit specified: #{v} valid limits are /^\d+%*$/" unless v =~ /^\d+%*$/
+
+          if v =~ /^\d+$/
+            options[:mcollective_limit_targets] = v.to_i
+          else
+            options[:mcollective_limit_targets] = v
+          end
+        end
+
+        parser.on('--json', '-j', 'Produce JSON output') do |v|
+          options[:progress_bar] = false
+          options[:output_format] = :json
+        end
+      end
+    end
+  end
+end