choria-mcorpc-support 0.0.1

data/lib/mcollective/ddl/base.rb

@@ -0,0 +1,217 @@
+module MCollective
+  module DDL
+    # The base class for all kinds of DDL files.  DDL files when
+    # run gets parsed and builds up a hash of the basic primitive
+    # types, ideally restricted so it can be converted to JSON though
+    # today there are some Ruby Symbols in them which might be fixed
+    # laster on.
+    #
+    # The Hash being built should be stored in @entities, the format
+    # is generally not prescribed but there's a definite feel to how
+    # DDL files look so study the agent and discovery ones to see how
+    # the structure applies to very different use cases.
+    #
+    # For every plugin type you should have a single word name - that
+    # corresponds to the directory in the libdir where these plugins
+    # live.  If you need anything above and beyond 'metadata' in your
+    # plugin DDL then add a PlugintypeDDL class here and add your
+    # specific behaviors to those.
+    class Base
+      attr_reader :meta, :entities, :pluginname, :plugintype, :usage, :requirements
+
+      def initialize(plugin, plugintype=:agent, loadddl=true)
+        @entities = {}
+        @meta = {}
+        @usage = ""
+        @config = Config.instance
+        @pluginname = plugin
+        @plugintype = plugintype.to_sym
+        @requirements = {}
+
+        loadddlfile if loadddl
+      end
+
+      # Generates help using the template based on the data
+      # created with metadata and input.
+      #
+      # If no template name is provided one will be chosen based
+      # on the plugin type.  If the provided template path is
+      # not absolute then the template will be loaded either from
+      # the config dir and if that does not exist, default to
+      # /etc/mcollective
+      def help(template=nil)
+        template = template_for_plugintype unless template
+        template = Util.templatepath(template) unless Util.absolute_path?(template)
+
+        template = File.read(template)
+        meta = @meta
+        entities = @entities
+
+        unless template == "metadata-help.erb"
+          metadata_template = Util.templatepath("metadata-help.erb")
+          metadata_template = File.read(metadata_template)
+          metastring = ERB.new(metadata_template, 0, '%')
+          metastring = metastring.result(binding)
+        end
+
+        erb = ERB.new(template, 0, '%')
+        erb.result(binding)
+      end
+
+      def usage(usage_text)
+        @usage = usage_text
+      end
+
+      def template_for_plugintype
+        case @plugintype
+        when :agent
+          return "rpc-help.erb"
+        else
+          if File.exists?(Util.templatepath("#{@plugintype}-help.erb"))
+            return "#{@plugintype}-help.erb"
+          else
+            # Default help template gets loaded if plugintype-help does not exist.
+            return "metadata-help.erb"
+          end
+        end
+      end
+
+      def loadddlfile
+        if ddlfile = findddlfile
+          instance_eval(File.read(ddlfile), ddlfile, 1)
+        else
+          raise("Can't find DDL for #{@plugintype} plugin '#{@pluginname}'")
+        end
+      end
+
+      def findddlfile(ddlname=nil, ddltype=nil)
+        ddlname = @pluginname unless ddlname
+        ddltype = @plugintype unless ddltype
+
+        @config.libdir.each do |libdir|
+          ddlfile = File.join([libdir, "mcollective", ddltype.to_s, "#{ddlname}.ddl"])
+          if File.exist?(ddlfile)
+            Log.debug("Found #{ddlname} ddl at #{ddlfile}")
+            return ddlfile
+          end
+        end
+        return false
+      end
+
+      def validate_requirements
+        if requirement = @requirements[:mcollective]
+          if Util.versioncmp(Util.mcollective_version, requirement) < 0
+            raise DDLValidationError, "%s plugin '%s' requires MCollective version %s or newer" % [@plugintype.to_s.capitalize, @pluginname, requirement]
+          end
+        end
+
+        true
+      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
+      def validate_input_argument(input, key, argument)
+        Validator.load_validators
+
+        case input[key][:type]
+        when :string
+          Validator.validate(argument, :string)
+
+          Validator.length(argument, input[key][:maxlength].to_i)
+
+          Validator.validate(argument, input[key][:validation])
+
+        when :list
+          Validator.validate(argument, input[key][:list])
+
+        else
+          Validator.validate(argument, input[key][:type])
+        end
+
+        return true
+      rescue => e
+        raise DDLValidationError, "Cannot validate input %s: %s" % [key, e.to_s]
+      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 entity input #{argument} belongs to" unless @current_entity
+
+        entity = @current_entity
+
+        [:prompt, :description, :type].each do |arg|
+          raise "Input needs a :#{arg} property" unless properties.include?(arg)
+        end
+
+        @entities[entity][:input][argument] = {:prompt => properties[:prompt],
+                                               :description => properties[:description],
+                                               :type => properties[:type],
+                                               :default => properties[:default],
+                                               :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)
+
+            @entities[entity][:input][argument][:validation] = properties[:validation]
+            @entities[entity][:input][argument][:maxlength] = properties[:maxlength]
+
+          when :list
+            raise "Input type :list needs a :list argument" unless properties.include?(:list)
+
+            @entities[entity][: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_entity
+        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_entity
+
+        @entities[action][:output][argument] = {:description => properties[:description],
+                                                :display_as  => properties[:display_as],
+                                                :default     => properties[:default]}
+      end
+
+      def requires(requirement)
+        raise "Requirement should be a hash in the form :item => 'requirement'" unless requirement.is_a?(Hash)
+
+        valid_requirements = [:mcollective]
+
+        requirement.keys.each do |key|
+          unless valid_requirements.include?(key)
+            raise "Requirement %s is not a valid requirement, only %s is supported" % [key, valid_requirements.join(", ")]
+          end
+
+          @requirements[key] = requirement[key]
+        end
+
+        validate_requirements
+      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} property" unless meta.include?(arg)
+        end
+
+        @meta = meta
+      end
+    end
+  end
+end

data/lib/mcollective/ddl/dataddl.rb

@@ -0,0 +1,56 @@
+module MCollective
+  module DDL
+    # A DDL file for the data query plugins.
+    #
+    # Query plugins can today take only one input by convention in the DDL that
+    # is called :query, otherwise the input is identical to the standard input.
+    #
+    # metadata    :name        => "Agent",
+    #             :description => "Meta data about installed MColletive Agents",
+    #             :author      => "R.I.Pienaar <rip@devco.net>",
+    #             :license     => "ASL 2.0",
+    #             :version     => "1.0",
+    #             :url         => "https://docs.puppetlabs.com/mcollective/",
+    #             :timeout     => 1
+    #
+    # dataquery :description => "Agent Meta Data" do
+    #     input :query,
+    #           :prompt => "Agent Name",
+    #           :description => "Valid agent name",
+    #           :type => :string,
+    #           :validation => /^[\w\_]+$/,
+    #           :maxlength => 20
+    #
+    #     [:license, :timeout, :description, :url, :version, :author].each do |item|
+    #       output item,
+    #              :description => "Agent #{item}",
+    #              :display_as => item.to_s.capitalize
+    #     end
+    # end
+    class DataDDL<Base
+      def dataquery(input, &block)
+        raise "Data queries need a :description" unless input.include?(:description)
+        raise "Data queries can only have one definition" if @entities[:data]
+
+        @entities[:data]  = {:description => input[:description],
+                             :input => {},
+                             :output => {}}
+
+        @current_entity = :data
+        block.call if block_given?
+        @current_entity = nil
+      end
+
+      def input(argument, properties)
+        raise "The only valid input name for a data query is 'query'" if argument != :query
+
+        super
+      end
+
+      # Returns the interface for the data query
+      def dataquery_interface
+        @entities[:data] || {}
+      end
+    end
+  end
+end

data/lib/mcollective/ddl/discoveryddl.rb

@@ -0,0 +1,52 @@
+module MCollective
+  module DDL
+    # DDL for discovery plugins, a full example can be seen below
+    #
+    # metadata    :name        => "mc",
+    #             :description => "MCollective Broadcast based discovery",
+    #             :author      => "R.I.Pienaar <rip@devco.net>",
+    #             :license     => "ASL 2.0",
+    #             :version     => "0.1",
+    #             :url         => "https://docs.puppetlabs.com/mcollective/",
+    #             :timeout     => 2
+    #
+    # discovery do
+    #     capabilities [:classes, :facts, :identity, :agents, :compound]
+    # end
+    class DiscoveryDDL<Base
+      def discovery_interface
+        @entities[:discovery]
+      end
+
+      # records valid capabilities for discovery plugins
+      def capabilities(*caps)
+        caps = [caps].flatten
+
+        raise "Discovery plugin capabilities can't be empty" if caps.empty?
+
+        caps.each do |cap|
+          if [:classes, :facts, :identity, :agents, :compound].include?(cap)
+            @entities[:discovery][:capabilities] << cap
+          else
+            raise "%s is not a valid capability, valid capabilities are :classes, :facts, :identity, :agents and :compound" % cap
+          end
+        end
+      end
+
+      # Creates the definition for new discovery plugins
+      #
+      #    discovery do
+      #       capabilities [:classes, :facts, :identity, :agents, :compound]
+      #    end
+      def discovery(&block)
+        raise "Discovery plugins can only have one definition" if @entities[:discovery]
+
+        @entities[:discovery] = {:capabilities => []}
+
+        @current_entity = :discovery
+        block.call if block_given?
+        @current_entity = nil
+      end
+    end
+  end
+end

data/lib/mcollective/ddl/validatorddl.rb

@@ -0,0 +1,6 @@
+module MCollective
+  module DDL
+    class ValidatorDDL<Base
+    end
+  end
+end

data/lib/mcollective/discovery.rb

@@ -0,0 +1,143 @@
+module MCollective
+  class Discovery
+    def initialize(client)
+      @known_methods = find_known_methods
+      @default_method = Config.instance.default_discovery_method
+      @client = client
+    end
+
+    def find_known_methods
+      PluginManager.find("discovery")
+    end
+
+    def has_method?(method)
+      @known_methods.include?(method)
+    end
+
+    def force_direct_mode?
+      discovery_method != "mc"
+    end
+
+    def discovery_method
+      method = "mc"
+
+      if @client.options[:discovery_method]
+        method = @client.options[:discovery_method]
+      else
+        method = @default_method
+      end
+
+      raise "Unknown discovery method %s" % method unless has_method?(method)
+
+      unless method == "mc"
+        raise "Custom discovery methods require direct addressing mode" unless Config.instance.direct_addressing
+      end
+
+      return method
+    end
+
+    def discovery_class
+      method = discovery_method.capitalize
+
+      PluginManager.loadclass("MCollective::Discovery::#{method}") unless self.class.const_defined?(method)
+
+      self.class.const_get(method)
+    end
+
+    def ddl
+      @ddl ||= DDL.new(discovery_method, :discovery)
+
+      # if the discovery method got changed we might have an old DDL cached
+      # this will detect that and reread the correct DDL from disk
+      unless @ddl.meta[:name] == discovery_method
+        @ddl = DDL.new(discovery_method, :discovery)
+      end
+
+      return @ddl
+    end
+
+    # Agent filters are always present no matter what, so we cant raise an error if the capabilities
+    # suggest the discovery method cant do agents we just have to rely on the discovery plugin to not
+    # do stupid things in the presense of a agent filter
+    def check_capabilities(filter)
+      capabilities = ddl.discovery_interface[:capabilities]
+
+      unless capabilities.include?(:classes)
+        raise "Cannot use class filters while using the '%s' discovery method" % discovery_method unless filter["cf_class"].empty?
+      end
+
+      unless capabilities.include?(:facts)
+        raise "Cannot use fact filters while using the '%s' discovery method" % discovery_method unless filter["fact"].empty?
+      end
+
+      unless capabilities.include?(:identity)
+        raise "Cannot use identity filters while using the '%s' discovery method" % discovery_method unless filter["identity"].empty?
+      end
+
+      unless capabilities.include?(:compound)
+        raise "Cannot use compound filters while using the '%s' discovery method" % discovery_method unless filter["compound"].empty?
+      end
+    end
+
+    # checks if compound filters are used and then forces the 'mc' discovery plugin
+    def force_discovery_method_by_filter(filter)
+      unless discovery_method == "mc"
+        unless filter["compound"].empty?
+          Log.info "Switching to mc discovery method because compound filters are used"
+          @client.options[:discovery_method] = "mc"
+
+          return true
+        end
+      end
+
+      return false
+    end
+
+    # if a compound filter is specified and it has any function
+    # then we read the DDL for each of those plugins and sum up
+    # the timeout declared in the DDL
+    def timeout_for_compound_filter(compound_filter)
+      return 0 if compound_filter.nil? || compound_filter.empty?
+
+      timeout = 0
+
+      compound_filter.each do |filter|
+        filter.each do |statement|
+          if statement["fstatement"]
+            pluginname = Data.pluginname(statement["fstatement"]["name"])
+            ddl = DDL.new(pluginname, :data)
+            timeout += ddl.meta[:timeout]
+          end
+        end
+      end
+
+      timeout
+    end
+
+    def discovery_timeout(timeout, filter)
+      timeout = ddl.meta[:timeout] unless timeout
+
+      unless (filter["compound"] && filter["compound"].empty?)
+        timeout + timeout_for_compound_filter(filter["compound"])
+      else
+        timeout
+      end
+    end
+
+    def discover(filter, timeout, limit)
+      raise "Limit has to be an integer" unless limit.is_a?(Integer)
+
+      force_discovery_method_by_filter(filter)
+
+      check_capabilities(filter)
+
+      discovered = discovery_class.discover(filter, discovery_timeout(timeout, filter), limit, @client)
+
+      if limit > 0
+        return discovered[0,limit]
+      else
+        return discovered
+      end
+    end
+  end
+end