mcollective-client 2.0.0 → 2.2.0

data/lib/mcollective/ddl/agentddl.rb

@@ -0,0 +1,185 @@
+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         => "http://marionette-collective.org/",
+    #             :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
+    #
+    #      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)
+        # 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
+
+      # 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] || {}
+
+        input.keys.each do |key|
+          unless input[key][:optional]
+            unless arguments.keys.include?(key)
+              raise DDLValidationError, "Action #{action} needs a #{key} argument"
+            end
+          end
+
+          if arguments.keys.include?(key)
+            validate_input_argument(input, key, arguments[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

data/lib/mcollective/ddl/base.rb

@@ -0,0 +1,220 @@
+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 relative to
+      # helptemplatedir configuration parameter
+      def help(template=nil)
+        template = template_for_plugintype unless template
+        template = File.join(@config.helptemplatedir, template) unless template.start_with?(File::SEPARATOR)
+
+        template = File.read(template)
+        meta = @meta
+        entities = @entities
+
+        unless template == "metadata-help.erb"
+          metadata_template = File.join(@config.helptemplatedir, "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?(File.join(@config.helptemplatedir,"#{@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.mcollective_version == "@DEVELOPMENT_VERSION@"
+            Log.warn("DDL requirements validation being skipped in development")
+            return true
+          end
+
+          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" % 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],
+                                               :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         => "http://marionette-collective.org/",
+    #             :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