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         => "https://docs.puppetlabs.com/mcollective/",
            :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

Methods

action   action_interface   actions   aggregate   display   input   is_function?   method_missing   new   set_default_input_arguments   summarize   validate_rpc_request  

Public Class methods

Public Instance methods

action(name, input, &block)

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
action_interface(name)

Returns the interface for a specific action

actions()

Returns an array of actions this agent support

display(pref)

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

is_function?(method_name)

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.

method_missing(name, *args, &block)

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

set_default_input_arguments(action, arguments)

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

summarize(&block)

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

validate_rpc_request(action, arguments)

Helper to use the DDL to figure out if the remote call to an agent should be allowed based on action name and inputs.

[Validate]