+ +
+ +In Files
+-
+
+
- lib/mcollective/rpc/client.rb + +
Parent
+ + + +Methods
+-
+
+
- ::new + +
- #agent_filter + +
- #aggregate_reply + +
- #batch_size= + +
- #batch_sleep_time= + +
- #call_agent + +
- #call_agent_batched + +
- #class_filter + +
- #collective= + +
- #compound_filter + +
- #custom_request + +
- #disconnect + +
- #discover + +
- #discovery_method= + +
- #discovery_options= + +
- #discovery_timeout + +
- #discovery_timeout= + +
- #fact_filter + +
- #fire_and_forget_request + +
- #help + +
- #identity_filter + +
- #identity_filter_discovery_optimization + +
- #limit_method= + +
- #limit_targets= + +
- #load_aggregate_functions + +
- #method_missing + +
- #new_request + +
- #options + +
- #pick_nodes_from_discovered + +
- #process_results_with_block + +
- #process_results_without_block + +
- #reset + +
- #reset_filter + +
- #rpc_result_from_reply + +
- #validate_request + +
Files
+-
+
+
- COPYING + +
- Gemfile + +
- README + +
- Rakefile + +
- client.cfg.dist + +
- data-help.erb + +
- discovery-help.erb + +
- facts.yaml.dist + +
- metadata-help.erb + +
- msg-help.erb + +
- rpc-help.erb + +
- server.cfg.dist + +
- PLACEHOLDER + +
- PLACEHOLDER + +
- action_snippet.erb + +
- data_input_snippet.erb + +
- ddl.erb + +
- plugin.erb + +
- en.yml + +
- mcollective.init + +
Class Index
+ ![[+]](../../images/find.png "show/hide quicksearch")
+
+
+ -
+
+
- MCollective + +
- MCollective::Agent + +
- MCollective::Agents + +
- MCollective::Aggregate + +
- MCollective::Aggregate::Base + +
- MCollective::Aggregate::Result + +
- MCollective::Aggregate::Result::Base + +
- MCollective::Aggregate::Result::CollectionResult + +
- MCollective::Aggregate::Result::NumericResult + +
- MCollective::Application + +
- MCollective::Applications + +
- MCollective::Cache + +
- MCollective::Client + +
- MCollective::CodedError + +
- MCollective::Config + +
- MCollective::Connector + +
- MCollective::Connector::Base + +
- MCollective::DDL + +
- MCollective::DDL::AgentDDL + +
- MCollective::DDL::Base + +
- MCollective::DDL::DataDDL + +
- MCollective::DDL::DiscoveryDDL + +
- MCollective::DDL::ValidatorDDL + +
- MCollective::DDLValidationError + +
- MCollective::Data + +
- MCollective::Data::Base + +
- MCollective::Data::Result + +
- MCollective::Discovery + +
- MCollective::Facts + +
- MCollective::Facts::Base + +
- MCollective::Generators + +
- MCollective::Generators::AgentGenerator + +
- MCollective::Generators::Base + +
- MCollective::Generators::DataGenerator + +
- MCollective::InvalidRPCData + +
- MCollective::Log + +
- MCollective::Logger + +
- MCollective::Logger::Base + +
- MCollective::Logger::Console_logger + +
- MCollective::Logger::File_logger + +
- MCollective::Logger::Syslog_logger + +
- MCollective::Matcher + +
- MCollective::Matcher::Parser + +
- MCollective::Matcher::Scanner + +
- MCollective::Message + +
- MCollective::MissingRPCData + +
- MCollective::MsgDoesNotMatchRequestID + +
- MCollective::MsgTTLExpired + +
- MCollective::NotTargettedAtUs + +
- MCollective::Optionparser + +
- MCollective::PluginManager + +
- MCollective::PluginPackager + +
- MCollective::PluginPackager::AgentDefinition + +
- MCollective::PluginPackager::StandardDefinition + +
- MCollective::RPC + +
- MCollective::RPC::ActionRunner + +
- MCollective::RPC::Agent + +
- MCollective::RPC::Audit + +
- MCollective::RPC::Client + +
- MCollective::RPC::Helpers + +
- MCollective::RPC::Progress + +
- MCollective::RPC::Reply + +
- MCollective::RPC::Request + +
- MCollective::RPC::Result + +
- MCollective::RPC::Stats + +
- MCollective::RPCAborted + +
- MCollective::RPCError + +
- MCollective::Registration + +
- MCollective::Registration::Base + +
- MCollective::Runner + +
- MCollective::RunnerStats + +
- MCollective::SSL + +
- MCollective::Security + +
- MCollective::Security::Base + +
- MCollective::SecurityValidationFailed + +
- MCollective::Shell + +
- MCollective::Translatable + +
- MCollective::UnixDaemon + +
- MCollective::UnknownRPCAction + +
- MCollective::UnknownRPCError + +
- MCollective::Util + +
- MCollective::Validator + +
- MCollective::ValidatorError + +
- MCollective::WindowsDaemon + +
- Array + +
- Dir + +
- Object + +
- String + +
- Symbol + +
MCollective::RPC::Client
+ +The main component of the Simple RPC client system, this wraps around MCollective::Client and just brings in a lot of convention and standard approached.
-Methods
- -Attributes
- -| agent | -[R] | -- |
| batch_mode | -[R] | -- |
| batch_size | -[R] | -- |
| batch_sleep_time | -[R] | -- |
| client | -[R] | -- |
| config | -[RW] | -- |
| ddl | -[R] | -- |
| default_discovery_method | -[R] | -- |
| discovery_method | -[R] | -- |
| discovery_options | -[R] | -- |
| filter | -[RW] | -- |
| limit_method | -[R] | -- |
| limit_seed | -[R] | -- |
| limit_targets | -[R] | -- |
| output_format | -[R] | -- |
| progress | -[RW] | -- |
| reply_to | -[RW] | -- |
| stats | -[R] | -- |
| timeout | -[RW] | -- |
| ttl | -[RW] | -- |
| verbose | -[RW] | -- |
Public Class methods
- --Creates a stub for a remote agent, you can pass in an options array in the flags which will then -be used else it will just create a default options array with filtering enabled based -on the standard command line use. +
Attributes
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Public Class Methods
+ + ++Creates a stub for a remote agent, you can pass in an options array in the +flags which will then be used else it will just create a default options +array with filtering enabled based on the standard command line use.
rpc = RPC::Client.new("rpctest", :configfile => "client.cfg", :options => options)
-You typically would not call this directly you‘d use MCollective::RPC#rpcclient instead which is +You typically would not call this directly you’d use MCollective::RPC#rpcclient instead which is a wrapper around this that can be used as a Mixin
- -
# File lib/mcollective/rpc/client.rb, line 20
20: def initialize(agent, flags = {})
@@ -391,55 +879,76 @@ a wrapper around this that can be used as a Mixin
115: @stdout = STDOUT
116: @stdout.sync = true
117: end
-118: end
-
- Public Instance methods
- - + + +Public Instance Methods
+ + +Sets the agent filter
- -
# File lib/mcollective/rpc/client.rb, line 422
422: def agent_filter(agent)
423: @filter["agent"] = @filter["agent"] | [agent]
424: @filter["agent"].compact!
425: reset
-426: end
-
- (Not documented)
+ + + +
# File lib/mcollective/rpc/client.rb, line 687
687: def aggregate_reply(reply, aggregate)
@@ -450,28 +959,36 @@ Sets the agent filter
692: rescue Exception => e
693: Log.error("Failed to calculate aggregate summaries for reply from %s, calculating summaries disabled: %s: %s (%s)" % [reply[:senderid], e.backtrace.first, e.to_s, e.class])
694: return nil
-695: end
-
- Sets the batch size, if the size is set to 0 that will disable batch mode
- -
# File lib/mcollective/rpc/client.rb, line 608
608: def batch_size=(limit)
@@ -479,59 +996,75 @@ Sets the batch size, if the size is set to 0 that will disable batch mode
610:
611: @batch_size = Integer(limit)
612: @batch_mode = @batch_size > 0
-613: end
-
- (Not documented)
+ + + +
# File lib/mcollective/rpc/client.rb, line 615
615: def batch_sleep_time=(time)
616: raise "Can only set batch sleep time if direct addressing is supported" unless Config.instance.direct_addressing
617:
618: @batch_sleep_time = Float(time)
-619: end
-
- Handles traditional calls to the remote agents with full stats blocks, non blocks and everything else supported.
Other methods of calling the nodes can reuse this code by for example -specifying custom options and discovery -data +specifying custom options and discovery data
- -
# File lib/mcollective/rpc/client.rb, line 844
844: def call_agent(action, args, opts, disc=:auto, &block)
@@ -609,38 +1142,46 @@ data
916: else
917: return [results].flatten
918: end
-919: end
-
- Calls an agent in a way very similar to call_agent but it supports batching the +href="Client.html#M000480">call_agent but it supports batching the queries to the network.
The result sets, stats, block handling etc is all exactly like you would -expect from normal call_agent. +expect from normal call_agent.
-This is used by method_missing and works +This is used by method_missing and works only with direct addressing mode
- -
# File lib/mcollective/rpc/client.rb, line 759
759: def call_agent_batched(action, args, opts, batch_size, sleep_time, &block)
@@ -721,56 +1262,72 @@ only with direct addressing mode
834: else
835: return [results].flatten
836: end
-837: end
-
- Sets the class filter
- -
# File lib/mcollective/rpc/client.rb, line 398
398: def class_filter(klass)
399: @filter["cf_class"] = @filter["cf_class"] | [klass]
400: @filter["cf_class"].compact!
401: reset
-402: end
-
- Sets the collective we are communicating with
- -
# File lib/mcollective/rpc/client.rb, line 573
573: def collective=(c)
@@ -779,62 +1336,74 @@ Sets the collective we are communicating with
576: @collective = c
577: @client.options = options
578: reset
-579: end
-
- Set a compound filter
- -
# File lib/mcollective/rpc/client.rb, line 436
436: def compound_filter(filter)
437: @filter["compound"] = @filter["compound"] | [Matcher.create_compound_callstack(filter)]
438: reset
-439: end
-
- Constructs custom requests with custom filters and discovery data the idea is that this would be used in web applications where you might be using a cached copy of data provided by a registration agent to figure out on your own what nodes will be responding and what your filter would be.
-This will help you essentially short -circuit the traditional cycle of: +This will help you essentially short circuit the traditional cycle of:
-mc discover / call / wait for discovered -nodes +mc discover / call / wait for discovered nodes
by doing discovery however you like, contructing a filter and a list of @@ -846,12 +1415,11 @@ the same way, stats will be handled the same way etcetc
If you just wanted to contact one machine for example with a client that -already has other filter options setup -you can do: +already has other filter options setup you can do:
-puppet.custom_request("runonce", {}, ["your.box.com"], -{:identity => "your.box.com"}) +puppet.custom_request(“runonce”, {}, +[“your.box.com“], {:identity => “your.box.com“})
This will do runonce action on just ‘your.box.com’, no @@ -864,9 +1432,11 @@ hash as a filter, this will force that request to be a directly addressed request which technically does not need filters. If you try to use this mode with direct addressing disabled an exception will be raise
- -
# File lib/mcollective/rpc/client.rb, line 296
296: def custom_request(action, args, expected_agents, filter = {}, &block)
@@ -915,51 +1485,65 @@ mode with direct addressing disabled an exception will be raise
339: else
340: call_agent(action, args, custom_options, [expected_agents].flatten)
341: end
-342: end
-
- Disconnects cleanly from the middleware
- -
# File lib/mcollective/rpc/client.rb, line 121
121: def disconnect
122: @client.disconnect
-123: end
-
- Does discovery based on the filters set, if a discovery was previously done -return that else do a new discovery. +return that else do a new discovery.
Alternatively if identity filters are given and none of them are regular @@ -977,12 +1561,13 @@ Will show a message indicating its doing discovery if running verbose or if the :verbose flag is passed in.
-Use reset to force a new discovery +Use reset to force a new discovery
- -
# File lib/mcollective/rpc/client.rb, line 468
468: def discover(flags={})
@@ -1069,23 +1654,29 @@ href="Client.html#M000085">new discovery
549: RPC.discovered(@discovered_agents)
550:
551: @discovered_agents
-552: end
-
- Sets the discovery method. If we change the method there are a number of steps to take:
@@ -1100,13 +1691,14 @@ steps to take:The remaining item is the discovery timeout, we leave that as is since that -is the user supplied timeout either via initial options or via specifically setting it on -the client. +is the user supplied timeout either via initial options or via specifically +setting it on the client.
- -
# File lib/mcollective/rpc/client.rb, line 377
377: def discovery_method=(method)
@@ -1122,73 +1714,100 @@ the client.
387: @client.options = options
388:
389: reset
-390: end
-
- (Not documented)
+ + + +
# File lib/mcollective/rpc/client.rb, line 392
392: def discovery_options=(options)
393: @discovery_options = [options].flatten
394: reset
-395: end
-
- (Not documented)
+ + + +
# File lib/mcollective/rpc/client.rb, line 344
344: def discovery_timeout
345: return @discovery_timeout if @discovery_timeout
346: return @client.discoverer.ddl.meta[:timeout]
-347: end
-
- (Not documented)
+ + + +
# File lib/mcollective/rpc/client.rb, line 349
349: def discovery_timeout=(timeout)
@@ -1203,28 +1822,36 @@ the client.
358: # calculate a correct timeout based on DDL timeout and the
359: # supplied discovery timeout
360: @timeout = @ddl.meta[:timeout] + discovery_timeout
-361: end
-
- Sets the fact filter
- -
# File lib/mcollective/rpc/client.rb, line 405
405: def fact_filter(fact, value=nil, operator="=")
@@ -1241,36 +1868,44 @@ Sets the fact filter
416:
417: @filter["fact"].compact!
418: reset
-419: end
-
- for requests that do not care for results just return the request id and -don‘t do any of the response processing. +don’t do any of the response processing.
We send the :process_results flag with to the nodes so they can make decisions based on that.
-Should only be called via method_missing +Should only be called via method_missing
- -
# File lib/mcollective/rpc/client.rb, line 710
710: def fire_and_forget_request(action, args, filter=nil)
@@ -1291,82 +1926,103 @@ Should only be called via method_missing
725: end
726:
727: client.sendreq(message, nil)
-728: end
-
- +Returns help for an agent if a DDL was found +
+ + + +
# File lib/mcollective/rpc/client.rb, line 126
126: def help(template)
127: @ddl.help(template)
-128: end
-
- Sets the identity filter
- -
# File lib/mcollective/rpc/client.rb, line 429
429: def identity_filter(identity)
430: @filter["identity"] = @filter["identity"] | [identity]
431: @filter["identity"].compact!
432: reset
-433: end
-
- if an identity filter is supplied and it is all strings no regex we can use that as discovery data, technically the identity filter is then redundant if we are in direct addressing mode and we could empty it out but this use -case should only really be for a few -I‘s on the CLI +case should only really be for a few -I’s on the CLI
For safety we leave the filter in place for now, that way we can support @@ -1377,9 +2033,11 @@ This is only needed for the ‘mc’ discovery method, other methods might change the concept of identity to mean something else so we should pass the full identity filter to them
- -
# File lib/mcollective/rpc/client.rb, line 741
741: def identity_filter_discovery_optimization
@@ -1391,29 +2049,39 @@ should pass the full identity filter to them
747: @force_direct_request = true if Config.instance.direct_addressing
748: end
749: end
-750: end
-
- -Sets and sanity check the limit_method variable used to determine how to -limit targets if limit_targets is set -
- -+Sets and sanity check the limit_method variable used to determine +how to limit targets if limit_targets is set +
+ + + +
# File lib/mcollective/rpc/client.rb, line 599
599: def limit_method=(method)
@@ -1422,29 +2090,38 @@ limit targets if limit_targets is set
602: raise "Unknown limit method #{method} must be :random or :first" unless [:random, :first].include?(method)
603:
604: @limit_method = method
-605: end
-
- -Sets and sanity checks the limit_targets variable used to restrict how many -nodes we‘ll target -
- -+Sets and sanity checks the limit_targets variable used to +restrict how many nodes we’ll target +
+ + + +
# File lib/mcollective/rpc/client.rb, line 583
583: def limit_targets=(limit)
@@ -1459,25 +2136,34 @@ nodes we‘ll target
592: else
593: @limit_targets = Integer(limit)
594: end
-595: end
-
- (Not documented)
+ + + +
# File lib/mcollective/rpc/client.rb, line 676
676: def load_aggregate_functions(action, ddl)
@@ -1489,28 +2175,34 @@ nodes we‘ll target
682: rescue => e
683: Log.error("Failed to load aggregate functions, calculating summaries disabled: %s: %s (%s)" % [e.backtrace.first, e.to_s, e.class])
684: return nil
-685: end
-
- Magic handler to invoke remote methods
Once the stub is created using the constructor or the RPC#rpcclient helper you can call remote +href="../RPC.html#M000314">RPC#rpcclient helper you can call remote actions easily:
@@ -1519,7 +2211,8 @@ actions easily:This will call the ‘echo’ action of the ‘rpctest’ agent and return the result as an array, the array will be a simplified -result set from the usual full MCollective::Client#req with additional +result set from the usual full MCollective::Client#req with additional error codes and error text:
@@ -1535,9 +2228,9 @@ error codes and error text: }
-If :statuscode is 0 then everything went find, if it‘s 1 then you +If :statuscode is 0 then everything went find, if it’s 1 then you supplied the correct arguments etc but the request could not be completed, -you‘ll find a human parsable reason in :statusmsg then. +you’ll find a human parsable reason in :statusmsg then.
Codes 2 to 5 maps directly to
- --To get access to the full result of the MCollective::Client#req calls you -can pass in a block: +To get access to the full result of the MCollective::Client#req calls you can +pass in a block:
rpc.echo(:msg => "hello world") do |resp| @@ -1558,8 +2252,9 @@ can pass in a block: end-In this case resp will the result from MCollective::Client#req. Instead of -returning simple text and codes as above you‘ll also need to handle +In this case resp will the result from MCollective::Client#req. Instead of +returning simple text and codes as above you’ll also need to handle the following exceptions:
@@ -1574,7 +2269,7 @@ prevented the agent from running
During calls a progress indicator will be shown of how many results -we‘ve received against how many nodes were discovered, you can +we’ve received against how many nodes were discovered, you can disable this by setting progress to false:
@@ -1582,7 +2277,7 @@ disable this by setting progress to false:This supports a 2nd mode where it will send the SimpleRPC request and never -handle the responses. It‘s a bit like UDP, it sends the request with +handle the responses. It’s a bit like UDP, it sends the request with the filter attached and you only get back the requestid, you have no indication about results.
@@ -1605,9 +2300,11 @@ Batched processing is supported: This will do everything exactly as normal but communicate to only 5 agents at a time+ + + +--# File lib/mcollective/rpc/client.rb, line 231 231: def method_missing(method_name, *args, &block) @@ -1645,28 +2342,34 @@ at a time 263: else 264: call_agent(action, args, options, :auto, &block) 265: end -266: end --
Creates a suitable request hash for the SimpleRPC agent.
-You‘d use this if you ever wanted to take care of sending requests on -your own - perhaps via Client#sendreq if you didn‘t care for +You’d use this if you ever wanted to take care of sending requests on +your own - perhaps via Client#sendreq if you didn’t care for responses.
@@ -1687,9 +2390,11 @@ all if the request was receieved or not Clearly the use of this technique should be limited and done only if your code requires such a thing
- -
# File lib/mcollective/rpc/client.rb, line 149
149: def new_request(action, data)
@@ -1701,29 +2406,37 @@ code requires such a thing
155: :action => action,
156: :caller => callerid,
157: :data => data}
-158: end
-
- -Provides a normal options hash like you -would get from Optionparser -
- -+Provides a normal options hash like you would get from Optionparser +
+ + + +
# File lib/mcollective/rpc/client.rb, line 556
556: def options
@@ -1740,23 +2453,29 @@ would get from Optionparser
567: :config => @config,
568: :publish_timeout => @publish_timeout,
569: :threaded => @threaded}
-570: end
-
- Pick a number of nodes from the discovered nodes
@@ -1774,9 +2493,11 @@ configuration option which can be either :first or anything else - if random chosen, and batch-seed set, then set srand for the generator, and reset afterwards -
-
# File lib/mcollective/rpc/client.rb, line 635
635: def pick_nodes_from_discovered(count)
@@ -1818,30 +2539,38 @@ configuration option which can be either :first or anything else
671: end
672:
673: [result].flatten
-674: end
-
- process client requests by calling a block on each result in this mode we do not do anything fancy with the result objects and we raise exceptions if there are problems with the data
- -
# File lib/mcollective/rpc/client.rb, line 944
944: def process_results_with_block(action, resp, block, aggregate)
@@ -1879,29 +2608,37 @@ there are problems with the data
976: end
977:
978: return aggregate
-979: end
-
- Handles result sets that has no block associated, sets fails and ok in the stats object and return a hash of the response to send to the caller
- -
# File lib/mcollective/rpc/client.rb, line 924
924: def process_results_without_block(resp, action, aggregate)
@@ -1918,101 +2655,132 @@ stats object and return a hash of the response to send to the caller
935: end
936:
937: [result, aggregate]
-938: end
-
- Resets various internal parts of the class, most importantly it clears out the cached discovery
- -
# File lib/mcollective/rpc/client.rb, line 443
443: def reset
444: @discovered_agents = nil
-445: end
-
- Reet the filter to an empty one
- -
# File lib/mcollective/rpc/client.rb, line 448
448: def reset_filter
449: @filter = Util.empty_filter
450: agent_filter @agent
-451: end
-
- (Not documented)
+ + + +
# File lib/mcollective/rpc/client.rb, line 697
697: def rpc_result_from_reply(agent, action, reply)
698: Result.new(agent, action, {:sender => reply[:senderid], :statuscode => reply[:body][:statuscode],
699: :statusmsg => reply[:body][:statusmsg], :data => reply[:body][:data]})
-700: end
-
- For the provided arguments and action the input arguments get modified by supplying any defaults provided in the DDL for arguments that were not supplied in the request @@ -2021,9 +2789,11 @@ arguments that were not supplied in the request We then pass the modified arguments to the DDL for validation
- -
# File lib/mcollective/rpc/client.rb, line 165
165: def validate_request(action, args)
@@ -2031,22 +2801,33 @@ for validation
167:
168: @ddl.set_default_input_arguments(action, args)
169: @ddl.validate_rpc_request(action, args)
-170: end
-
-