choria-mcorpc-support 0.0.1

data/lib/mcollective/data/collective_data.ddl

@@ -0,0 +1,20 @@
+metadata    :name        => "Collective",
+            :description => "Collective membership",
+            :author      => "Puppet Labs",
+            :license     => "ASL 2.0",
+            :version     => "1.0",
+            :url         => "https://docs.puppetlabs.com/mcollective/",
+            :timeout     => 1
+
+dataquery :description => "Collective" do
+  input :query,
+        :prompt => 'Collective',
+        :description => 'Collective name to ask about, eg mcollective',
+        :type => :string,
+        :validation => /./,
+        :maxlength => 256
+
+  output :member,
+        :description => 'Node is a member of the named collective',
+        :display_as => 'member'
+end

data/lib/mcollective/data/collective_data.rb

@@ -0,0 +1,9 @@
+module MCollective
+  module Data
+    class Collective_data<Base
+      query do |collective|
+        result[:member] = Config.instance.collectives.include?(collective)
+      end
+    end
+  end
+end

data/lib/mcollective/data/fact_data.ddl

@@ -0,0 +1,28 @@
+metadata    :name        => "Fact",
+            :description => "Structured fact query",
+            :author      => "Puppet Labs",
+            :license     => "ASL 2.0",
+            :version     => "1.0",
+            :url         => "https://docs.puppetlabs.com/mcollective/",
+            :timeout     => 1
+
+dataquery :description => "Fact" do
+  input :query,
+        :prompt => 'Fact Path',
+        :description => 'Path to a fact, eg network.eth0.address',
+        :type => :string,
+        :validation => /./,
+        :maxlength => 256
+
+  output :exists,
+        :description => 'Fact is present',
+        :display_as => 'exists'
+
+  output :value,
+        :description => 'Fact value',
+        :display_as => 'value'
+
+  output :value_encoding,
+        :description => 'Encoding of the fact value (text/plain or application/json)',
+        :display_as => 'value_encoding'
+end

data/lib/mcollective/data/fact_data.rb

@@ -0,0 +1,55 @@
+module MCollective
+  module Data
+    class Fact_data<Base
+      query do |path|
+        parts = path.split /\./
+        walk_path(parts)
+      end
+
+      private
+
+      def walk_path(path)
+        # Set up results as though we didn't find the value
+        result[:exists] = false
+        result[:value] = false
+        result[:value_encoding] = false
+
+        facts = PluginManager['facts_plugin'].get_facts
+
+        path.each do |level|
+          case facts
+          when Array
+            level = Integer(level)
+            if level >= facts.size
+              # array index out would be out of bounds, so we don't have the value
+              return
+            end
+          when Hash
+            if !facts.include?(level)
+              # we don't have the key for the next level, so give up
+              return
+            end
+          else
+            # this isn't a container data type, so we can't walk into it
+            return
+          end
+
+          facts = facts[level]
+        end
+
+        result[:exists] = true
+        case facts
+        when Array, Hash
+          # Currently data plugins cannot return structured data, so until
+          # this is fixed flatten the data with json and flag that we have
+          # munged the data
+          result[:value] = facts.to_json
+          result[:value_encoding] = 'application/json'
+        else
+          result[:value] = facts
+          result[:value_encoding] = 'text/plain'
+        end
+      end
+    end
+  end
+end

data/lib/mcollective/data/fstat_data.ddl

@@ -0,0 +1,89 @@
+metadata    :name        => "File Stat",
+            :description => "Retrieve file stat data for a given file",
+            :author      => "R.I.Pienaar <rip@devco.net>",
+            :license     => "ASL 2.0",
+            :version     => "1.0",
+            :url         => "https://docs.puppetlabs.com/mcollective/",
+            :timeout     => 1
+
+dataquery :description => "File stat information" do
+    input :query,
+          :prompt => "File Name",
+          :description => "Valid File Name",
+          :type => :string,
+          :validation => /.+/,
+          :maxlength => 120
+
+    output :name,
+           :description => "File name",
+           :display_as => "Name"
+
+    output :output,
+           :description => "Human readable information about the file",
+           :display_as => "Status"
+
+    output :present,
+           :description => "Indicates if the file exist using 0 or 1",
+           :display_as => "Present"
+
+    output :size,
+           :description => "File size",
+           :display_as => "Size"
+
+    output :mode,
+           :description => "File mode",
+           :display_as => "Mode"
+
+    output :md5,
+           :description => "File MD5 digest",
+           :display_as => "MD5"
+
+    output :mtime,
+           :description => "File modification time",
+           :display_as => "Modification time"
+
+    output :ctime,
+           :description => "File change time",
+           :display_as => "Change time"
+
+    output :atime,
+           :description => "File access time",
+           :display_as => "Access time"
+
+    output :mtime_seconds,
+           :description => "File modification time in seconds",
+           :display_as => "Modification time"
+
+    output :ctime_seconds,
+           :description => "File change time in seconds",
+           :display_as => "Change time"
+
+    output :atime_seconds,
+           :description => "File access time in seconds",
+           :display_as => "Access time"
+
+    output :mtime_age,
+           :description => "File modification age in seconds",
+           :display_as => "Modification age"
+
+    output :ctime_age,
+           :description => "File change age in seconds",
+           :display_as => "Change age"
+
+    output :atime_age,
+           :description => "File access age in seconds",
+           :display_as => "Access age"
+
+    output :uid,
+           :description => "File owner",
+           :display_as => "Owner"
+
+    output :gid,
+           :description => "File group",
+           :display_as => "Group"
+
+    output :type,
+           :description => "File type",
+           :display_as => "Type"
+end
+

data/lib/mcollective/data/fstat_data.rb

@@ -0,0 +1,56 @@
+module MCollective
+  module Data
+    class Fstat_data<Base
+      query do |file|
+        result[:name] = file
+        result[:output] = "not present"
+        result[:type] = "unknown"
+        result[:mode] = "0000"
+        result[:present] = 0
+        result[:size] = 0
+        result[:mtime] = 0
+        result[:ctime] = 0
+        result[:atime] = 0
+        result[:mtime_seconds] = 0
+        result[:ctime_seconds] = 0
+        result[:atime_seconds] = 0
+        result[:md5] = 0
+        result[:uid] = 0
+        result[:gid] = 0
+
+
+        if File.exists?(file)
+          result[:output] = "present"
+          result[:present] = 1
+
+          if File.symlink?(file)
+            stat = File.lstat(file)
+          else
+            stat = File.stat(file)
+          end
+
+          [:size, :uid, :gid].each do |item|
+            result[item] = stat.send(item)
+          end
+
+          [:mtime, :ctime, :atime].each do |item|
+            result[item] = stat.send(item).strftime("%F %T")
+            result["#{item}_seconds".to_sym] = stat.send(item).to_i
+            result["#{item}_age".to_sym] = Time.now.to_i - stat.send(item).to_i
+          end
+
+          result[:mode] = "%o" % [stat.mode]
+          result[:md5] = Digest::MD5.hexdigest(File.read(file)) if stat.file?
+
+          result[:type] = "directory" if stat.directory?
+          result[:type] = "file" if stat.file?
+          result[:type] = "symlink" if stat.symlink?
+          result[:type] = "socket" if stat.socket?
+          result[:type] = "chardev" if stat.chardev?
+          result[:type] = "blockdev" if stat.blockdev?
+        end
+      end
+    end
+  end
+end
+

data/lib/mcollective/data/result.rb

@@ -0,0 +1,45 @@
+module MCollective
+  module Data
+    class Result
+      # remove some methods that might clash with commonly
+      # used return data to improve the effectiveness of the
+      # method_missing lookup strategy
+      undef :type if method_defined?(:type)
+
+      def initialize(outputs)
+        @data = {}
+
+        outputs.keys.each do |output|
+          @data[output] = Marshal.load(Marshal.dump(outputs[output].fetch(:default, nil)))
+        end
+      end
+
+      def include?(key)
+        @data.include?(key.to_sym)
+      end
+
+      def [](key)
+        @data[key.to_sym]
+      end
+
+      def []=(key, val)
+        # checks using the string representation of the class name to avoid deprecations on Bignum and Fixnum
+        raise "Can only store String, Integer, Float or Boolean data but got #{val.class} for key #{key}" unless ["String", "Integer", "Bignum", "Fixnum", "Float", "TrueClass", "FalseClass"].include?(val.class.to_s)
+
+        @data[key.to_sym] = val
+      end
+
+      def keys
+        @data.keys
+      end
+
+      def method_missing(method, *args)
+        key = method.to_sym
+
+        raise NoMethodError, "undefined local variable or method `%s'" % key unless include?(key)
+
+        @data[key]
+      end
+    end
+  end
+end

data/lib/mcollective/ddl.rb

@@ -0,0 +1,113 @@
+module MCollective
+  # A set of classes that helps create data description language files
+  # for plugins.  You can define meta data, actions, input and output
+  # describing the behavior of your agent or other plugins
+  #
+  # DDL files are used for input validation, constructing outputs,
+  # producing online help, informing the various display routines and
+  # so forth.
+  #
+  # A sample DDL for an agent 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
+  #
+  # There are now many types of DDL and ultimately all pugins should have
+  # DDL files.  The code is organized so that any plugin type will magically
+  # just work - they will be an instane of Base which has #metadata and a few
+  # common cases.
+  #
+  # For plugin types that require more specific behaviors they can just add a
+  # class here that inherits from Base and add their specific behavior.
+  #
+  # Base defines a specific behavior for input, output and metadata which we'd
+  # like to keep standard across plugin types so do not completely override the
+  # behavior of input.  The methods are written that they will gladly store extra
+  # content though so you add, do not remove.  See the AgentDDL class for an example
+  # where agents want a :required argument to be always set.
+  module DDL
+    require "mcollective/ddl/base"
+    require "mcollective/ddl/agentddl"
+    require "mcollective/ddl/dataddl"
+    require "mcollective/ddl/discoveryddl"
+
+    # There used to be only one big nasty DDL class with a bunch of mashed
+    # together behaviors.  It's been around for ages and we would rather not
+    # ask all the users to change their DDL.new calls to some other factory
+    # method that would have this exact same behavior.
+    #
+    # So we override the behavior of #new which is a hugely sucky thing to do
+    # but ultimately it's what would be least disrupting to code out there
+    # today.  We did though change DDL to a module to make it possibly a
+    # little less suprising, possibly.
+    def self.new(*args, &blk)
+      load_and_cache(*args)
+    end
+
+    def self.load_and_cache(*args)
+      Cache.setup(:ddl, 300)
+
+      plugin = args.first
+      args.size > 1 ? type = args[1].to_s : type = "agent"
+      path = "%s/%s" % [type, plugin]
+
+      begin
+        ddl = Cache.read(:ddl, path)
+      rescue
+        begin
+          klass = DDL.const_get("%sDDL" % type.capitalize)
+        rescue NameError
+          klass = Base
+        end
+
+        ddl = Cache.write(:ddl, path, klass.new(*args))
+      end
+
+      return ddl
+    end
+
+    # As we're taking arguments on the command line we need a
+    # way to input booleans, true on the cli is a string so this
+    # method will take the ddl, find all arguments that are supposed
+    # to be boolean and if they are the strings "true"/"yes" or "false"/"no"
+    # turn them into the matching boolean
+    def self.string_to_boolean(val)
+      return true if ["true", "t", "yes", "y", "1"].include?(val.downcase)
+      return false if ["false", "f", "no", "n", "0"].include?(val.downcase)
+
+      raise "#{val} does not look like a boolean argument"
+    end
+
+    # a generic string to number function, if a number looks like a float
+    # it turns it into a float else an int.  This is naive but should be sufficient
+    # for numbers typed on the cli in most cases
+    def self.string_to_number(val)
+      return val.to_f if val =~ /^\d+\.\d+$/
+      return val.to_i if val =~ /^\d+$/
+
+      raise "#{val} does not look like a number"
+    end
+  end
+end

data/lib/mcollective/ddl/agentddl.rb

@@ -0,0 +1,253 @@
+module MCollective
+  module DDL
+    # A DDL class specific to agent plugins.
+    #
+    # A full DDL can be seen below with all the possible bells and whistles present.
+    #
+    # metadata    :name        => "Utilities and Helpers for SimpleRPC Agents",
+    #             :description => "General helpful actions that expose stats and internals to SimpleRPC clients",
+    #             :author      => "R.I.Pienaar <rip@devco.net>",
+    #             :license     => "Apache License, Version 2.0",
+    #             :version     => "1.0",
+    #             :url         => "https://docs.puppetlabs.com/mcollective/",
+    #             :timeout     => 10
+    #
+    # action "get_fact", :description => "Retrieve a single fact from the fact store" do
+    #      display :always
+    #
+    #      input :fact,
+    #            :prompt      => "The name of the fact",
+    #            :description => "The fact to retrieve",
+    #            :type        => :string,
+    #            :validation  => '^[\w\-\.]+$',
+    #            :optional    => false,
+    #            :maxlength   => 40,
+    #            :default     => "fqdn"
+    #
+    #      output :fact,
+    #             :description => "The name of the fact being returned",
+    #             :display_as  => "Fact"
+    #
+    #      output :value,
+    #             :description => "The value of the fact",
+    #             :display_as  => "Value",
+    #             :default     => ""
+    #
+    #     summarize do
+    #         aggregate summary(:value)
+    #     end
+    # end
+    class AgentDDL<Base
+      def initialize(plugin, plugintype=:agent, loadddl=true)
+        @process_aggregate_functions = nil
+
+        super
+      end
+
+      def input(argument, properties)
+        raise "Input needs a :optional property" unless properties.include?(:optional)
+
+        super
+      end
+
+      # Calls the summarize block defined in the ddl. Block will not be called
+      # if the ddl is getting processed on the server side. This means that
+      # aggregate plugins only have to be present on the client side.
+      #
+      # The @process_aggregate_functions variable is used by the method_missing
+      # block to determine if it should kick in, this way we very tightly control
+      # where we activate the method_missing behavior turning it into a noop
+      # otherwise to maximise the chance of providing good user feedback
+      def summarize(&block)
+        unless @config.mode == :server
+          @process_aggregate_functions = true
+          block.call
+          @process_aggregate_functions = nil
+        end
+      end
+
+      # Sets the aggregate array for the given action
+      def aggregate(function, format = {:format => nil})
+        raise(DDLValidationError, "Formats supplied to aggregation functions should be a hash") unless format.is_a?(Hash)
+        raise(DDLValidationError, "Formats supplied to aggregation functions must have a :format key") unless format.keys.include?(:format)
+        raise(DDLValidationError, "Functions supplied to aggregate should be a hash") unless function.is_a?(Hash)
+
+        unless (function.keys.include?(:args)) && function[:args]
+          raise DDLValidationError, "aggregate method for action '%s' missing a function parameter" % entities[@current_entity][:action]
+        end
+
+        entities[@current_entity][:aggregate] ||= []
+        entities[@current_entity][:aggregate] << (format[:format].nil? ? function : function.merge(format))
+      end
+
+      # Sets the display preference to either :ok, :failed, :flatten or :always
+      # operates on action level
+      def display(pref)
+        if pref == :flatten
+          Log.warn("The display option :flatten is being deprecated and will be removed in the next minor release.")
+        end
+
+        # 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_entity
+        @entities[action][:display] = pref
+      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 property" unless input.include?(:description)
+
+        unless @entities.include?(name)
+          @entities[name] = {}
+          @entities[name][:action] = name
+          @entities[name][:input] = {}
+          @entities[name][:output] = {}
+          @entities[name][:display] = :failed
+          @entities[name][:description] = input[:description]
+        end
+
+        # if a block is passed it might be creating input methods, call it
+        # we set @current_entity so the input block can know what its talking
+        # to, this is probably an epic hack, need to improve.
+        @current_entity = name
+        block.call if block_given?
+        @current_entity = nil
+      end
+
+      # If the method name matches a # aggregate function, we return the function
+      # with args as a hash.  This will only be active if the @process_aggregate_functions
+      # is set to true which only happens in the #summarize block
+      def method_missing(name, *args, &block)
+        unless @process_aggregate_functions || is_function?(name)
+          raise NoMethodError, "undefined local variable or method `#{name}'", caller
+        end
+
+        return {:function => name, :args => args}
+      end
+
+      # Checks if a method name matches a aggregate plugin.
+      # This is used by method missing so that we dont greedily assume that
+      # every method_missing call in an agent ddl has hit a aggregate function.
+      def is_function?(method_name)
+        PluginManager.find("aggregate").include?(method_name.to_s)
+      end
+
+      # For a given action and arguments look up the DDL interface to that action
+      # and if any arguments in the DDL have a :default value assign that to any
+      # input that does not have an argument in the input arguments
+      #
+      # This is intended to only be called on clients and not on servers as the
+      # clients should never be able to publish non compliant requests and the
+      # servers should really not tamper with incoming requests since doing so
+      # might raise validation errors that were not raised on the client breaking
+      # our fail-fast approach to input validation
+      def set_default_input_arguments(action, arguments)
+        input = action_interface(action)[:input]
+
+        return unless input
+
+        input.keys.each do |key|
+          if key.is_a?(Symbol) && arguments.include?(key.to_s) && !input.include?(key.to_s)
+            compat_arg = key.to_s
+          else
+            compat_arg = key
+          end
+
+          if !arguments.include?(compat_arg) && !input[key][:default].nil? && !input[key][:optional]
+            Log.debug("Setting default value for input '%s' to '%s'" % [key, input[key][:default]])
+            arguments[compat_arg] = input[key][:default]
+          end
+        end
+      end
+
+      # Creates a new set of arguments with string arguments mapped to symbol ones
+      #
+      # This is to assist with moving to a JSON pure world where requests might come
+      # in from REST or other languages, those languages and indeed JSON itself does
+      # not support symbols.
+      #
+      # It ensures a backward compatible mode where for rpcutil both of these requests
+      # are equivelant
+      #
+      #   c.get_fact(:fact => "cluster")
+      #   c.get_fact("fact" => "cluster")
+      #
+      # The case where both :fact and "fact" is in the DDL cannot be handled correctly
+      # and this code will assume the caller means "fact" in that case.  There's no
+      # way to represent such a request in JSON and just in general sounds like a bad
+      # idea, so a warning is logged which would in default client configuration appear
+      # on the clients display
+      def symbolize_basic_input_arguments(input, arguments)
+        warned = false
+
+        Hash[arguments.map do |key, value|
+          if input.include?(key.intern) && input.include?(key.to_s) && !warned
+            Log.warn("String and Symbol versions of input %s found in the DDL for %s, ensure your DDL keys are unique." % [key, @pluginname])
+            warned = true
+          end
+
+          if key.is_a?(String) && input.include?(key.intern) && !input.include?(key)
+            [key.intern, value]
+          else
+            [key, value]
+          end
+        end]
+      end
+
+      # Helper to use the DDL to figure out if the remote call to an
+      # agent should be allowed based on action name and inputs.
+      def validate_rpc_request(action, arguments)
+        # is the action known?
+        unless actions.include?(action)
+          raise DDLValidationError, "Attempted to call action #{action} for #{@pluginname} but it's not declared in the DDL"
+        end
+
+        input = action_interface(action)[:input] || {}
+        compatible_args = symbolize_basic_input_arguments(input, arguments)
+
+        input.keys.each do |key|
+          unless input[key][:optional]
+            unless compatible_args.include?(key)
+              raise DDLValidationError, "Action #{action} needs a #{key} argument"
+            end
+          end
+
+          if compatible_args.include?(key)
+            validate_input_argument(input, key, compatible_args[key])
+          end
+        end
+
+        true
+      end
+
+      # Returns the interface for a specific action
+      def action_interface(name)
+        @entities[name] || {}
+      end
+
+      # Returns an array of actions this agent support
+      def actions
+        @entities.keys
+      end
+    end
+  end
+end