| Class | -MCollective::DDL::AgentDDL | -
| In: | -
-
- lib/mcollective/ddl/agentddl.rb
-
- - |
-
| Parent: | -- - Base - - | -
-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, - :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 -
- -- # File lib/mcollective/ddl/agentddl.rb, line 41 -41: def initialize(plugin, plugintype=:agent, loadddl=true) -42: @process_aggregate_functions = nil -43: -44: super -45: 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 -- -
- # File lib/mcollective/ddl/agentddl.rb, line 112 -112: def action(name, input, &block) -113: raise "Action needs a :description property" unless input.include?(:description) -114: -115: unless @entities.include?(name) -116: @entities[name] = {} -117: @entities[name][:action] = name -118: @entities[name][:input] = {} -119: @entities[name][:output] = {} -120: @entities[name][:display] = :failed -121: @entities[name][:description] = input[:description] -122: end -123: -124: # if a block is passed it might be creating input methods, call it -125: # we set @current_entity so the input block can know what its talking -126: # to, this is probably an epic hack, need to improve. -127: @current_entity = name -128: block.call if block_given? -129: @current_entity = nil -130: end --
-Sets the aggregate array for the given -action -
- -- # File lib/mcollective/ddl/agentddl.rb, line 70 -70: def aggregate(function, format = {:format => nil}) -71: DDL.validation_fail!(:PLMC28, "Formats supplied to aggregation functions should be a hash", :error) unless format.is_a?(Hash) -72: DDL.validation_fail!(:PLMC27, "Formats supplied to aggregation functions must have a :format key", :error) unless format.keys.include?(:format) -73: DDL.validation_fail!(:PLMC26, "Functions supplied to aggregate should be a hash", :error) unless function.is_a?(Hash) -74: -75: unless (function.keys.include?(:args)) && function[:args] -76: DDL.validation_fail!(:PLMC25, "aggregate method for action '%{action}' missing a function parameter", :error, :action => entities[@current_entity][:action]) -77: end -78: -79: entities[@current_entity][:aggregate] ||= [] -80: entities[@current_entity][:aggregate] << (format[:format].nil? ? function : function.merge(format)) -81: end --
-Sets the display preference to either -:ok, :failed, :flatten or :always operates on action level -
- -- # File lib/mcollective/ddl/agentddl.rb, line 85 -85: def display(pref) -86: # defaults to old behavior, complain if its supplied and invalid -87: unless [:ok, :failed, :flatten, :always].include?(pref) -88: raise "Display preference #{pref} is not valid, should be :ok, :failed, :flatten or :always" -89: end -90: -91: action = @current_entity -92: @entities[action][:display] = pref -93: end --
- # File lib/mcollective/ddl/agentddl.rb, line 47 -47: def input(argument, properties) -48: raise "Input needs a :optional property" unless properties.include?(:optional) -49: -50: super -51: 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. -
- -- # File lib/mcollective/ddl/agentddl.rb, line 146 -146: def is_function?(method_name) -147: PluginManager.find("aggregate").include?(method_name.to_s) -148: 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 -
- -- # File lib/mcollective/ddl/agentddl.rb, line 135 -135: def method_missing(name, *args, &block) -136: unless @process_aggregate_functions || is_function?(name) -137: raise NoMethodError, "undefined local variable or method `#{name}'", caller -138: end -139: -140: return {:function => name, :args => args} -141: 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 -
- -- # File lib/mcollective/ddl/agentddl.rb, line 159 -159: def set_default_input_arguments(action, arguments) -160: input = action_interface(action)[:input] -161: -162: return unless input -163: -164: input.keys.each do |key| -165: if !arguments.include?(key) && !input[key][:default].nil? && !input[key][:optional] -166: Log.debug("Setting default value for input '%s' to '%s'" % [key, input[key][:default]]) -167: arguments[key] = input[key][:default] -168: end -169: end -170: 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 -
- -- # File lib/mcollective/ddl/agentddl.rb, line 61 -61: def summarize(&block) -62: unless @config.mode == :server -63: @process_aggregate_functions = true -64: block.call -65: @process_aggregate_functions = nil -66: end -67: 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. -
- -- # File lib/mcollective/ddl/agentddl.rb, line 174 -174: def validate_rpc_request(action, arguments) -175: # is the action known? -176: unless actions.include?(action) -177: DDL.validation_fail!(:PLMC29, "Attempted to call action %{action} for %{plugin} but it's not declared in the DDL", :debug, :action => action, :plugin => @pluginname) -178: end -179: -180: input = action_interface(action)[:input] || {} -181: -182: input.keys.each do |key| -183: unless input[key][:optional] -184: unless arguments.keys.include?(key) -185: DDL.validation_fail!(:PLMC30, "Action '%{action}' needs a '%{key}' argument", :debug, :action => action, :key => key) -186: end -187: end -188: -189: if arguments.keys.include?(key) -190: validate_input_argument(input, key, arguments[key]) -191: end -192: end -193: -194: true -195: end --