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

     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

Methods

Public Class methods

[Source]

    # File lib/mcollective/ddl/agentddl.rb, line 40
40:       def initialize(plugin, plugintype=:agent, loadddl=true)
41:         @process_aggregate_functions = nil
42: 
43:         super
44:       end

Public Instance methods

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

[Source]

     # File lib/mcollective/ddl/agentddl.rb, line 111
111:       def action(name, input, &block)
112:         raise "Action needs a :description property" unless input.include?(:description)
113: 
114:         unless @entities.include?(name)
115:           @entities[name] = {}
116:           @entities[name][:action] = name
117:           @entities[name][:input] = {}
118:           @entities[name][:output] = {}
119:           @entities[name][:display] = :failed
120:           @entities[name][:description] = input[:description]
121:         end
122: 
123:         # if a block is passed it might be creating input methods, call it
124:         # we set @current_entity so the input block can know what its talking
125:         # to, this is probably an epic hack, need to improve.
126:         @current_entity = name
127:         block.call if block_given?
128:         @current_entity = nil
129:       end

Returns the interface for a specific action

[Source]

     # File lib/mcollective/ddl/agentddl.rb, line 175
175:       def action_interface(name)
176:         @entities[name] || {}
177:       end

Returns an array of actions this agent support

[Source]

     # File lib/mcollective/ddl/agentddl.rb, line 180
180:       def actions
181:         @entities.keys
182:       end

Sets the aggregate array for the given action

[Source]

    # File lib/mcollective/ddl/agentddl.rb, line 69
69:       def aggregate(function, format = {:format => nil})
70:         raise(DDLValidationError, "Formats supplied to aggregation functions should be a hash") unless format.is_a?(Hash)
71:         raise(DDLValidationError, "Formats supplied to aggregation functions must have a :format key") unless format.keys.include?(:format)
72:         raise(DDLValidationError, "Functions supplied to aggregate should be a hash") unless function.is_a?(Hash)
73: 
74:         unless (function.keys.include?(:args)) && function[:args]
75:           raise DDLValidationError, "aggregate method for action '%s' missing a function parameter" % entities[@current_entity][:action]
76:         end
77: 
78:         entities[@current_entity][:aggregate] ||= []
79:         entities[@current_entity][:aggregate] << (format[:format].nil? ? function : function.merge(format))
80:       end

Sets the display preference to either :ok, :failed, :flatten or :always operates on action level

[Source]

    # File lib/mcollective/ddl/agentddl.rb, line 84
84:       def display(pref)
85:         # defaults to old behavior, complain if its supplied and invalid
86:         unless [:ok, :failed, :flatten, :always].include?(pref)
87:           raise "Display preference #{pref} is not valid, should be :ok, :failed, :flatten or :always"
88:         end
89: 
90:         action = @current_entity
91:         @entities[action][:display] = pref
92:       end

[Source]

    # File lib/mcollective/ddl/agentddl.rb, line 46
46:       def input(argument, properties)
47:         raise "Input needs a :optional property" unless properties.include?(:optional)
48: 
49:         super
50:       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.

[Source]

     # File lib/mcollective/ddl/agentddl.rb, line 145
145:       def is_function?(method_name)
146:         PluginManager.find("aggregate").include?(method_name.to_s)
147:       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

[Source]

     # File lib/mcollective/ddl/agentddl.rb, line 134
134:       def method_missing(name, *args, &block)
135:         unless @process_aggregate_functions || is_function?(name)
136:           raise NoMethodError, "undefined local variable or method `#{name}'", caller
137:         end
138: 
139:         return {:function => name, :args => args}
140:       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

[Source]

    # File lib/mcollective/ddl/agentddl.rb, line 60
60:       def summarize(&block)
61:         unless @config.mode == :server
62:           @process_aggregate_functions = true
63:           block.call
64:           @process_aggregate_functions = nil
65:         end
66:       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.

[Source]

     # File lib/mcollective/ddl/agentddl.rb, line 151
151:       def validate_rpc_request(action, arguments)
152:         # is the action known?
153:         unless actions.include?(action)
154:           raise DDLValidationError, "Attempted to call action #{action} for #{@pluginname} but it's not declared in the DDL"
155:         end
156: 
157:         input = action_interface(action)[:input] || {}
158: 
159:         input.keys.each do |key|
160:           unless input[key][:optional]
161:             unless arguments.keys.include?(key)
162:               raise DDLValidationError, "Action #{action} needs a #{key} argument"
163:             end
164:           end
165: 
166:           if arguments.keys.include?(key)
167:             validate_input_argument(input, key, arguments[key])
168:           end
169:         end
170: 
171:         true
172:       end

[Validate]