| 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