SimpleRPC Message Format

SimpleRPC has a specific message structure that builds on the core MessageFormat. As such SimpleRPC is simply a plugin developed ontop of The Marionette Collective rather than an integrated part.

The core messages has a :body structure where agents and clients can send any data between nodes and clients. All the SimpleRPC structures below goes in this body. Filters, targets etc all use the standard core MessageFormat.

Requests

A basic SimpleRPC message can be seen below:

{:agent           => "echo",
 :action          => "echo",
 :caller          => "cert=rip",
 :data            => {:message => "hello world"},
 :process_results => true}

This structure will be sent as the :body of the core message, you might create this request using the command below:

e = rpcclient("echo")
  e.echo(:message => "hello world")

:agent

Records the agent that this message is targetted at.

:action

The action being called. As the core protocol has no concept of actions per agent this provides the needed data to route the request to the right code in the SimpleRPC agent

:caller

The callerid initiating the request. This is redundant and might be removed later since the core message format also includes this information - the core did not always include it. Removing it will only break backwards compatability with really old versions.

:data

The data being sent to the SimpleRPC action as its request structure, technically this can be any data but by SimpleRPC convention this would be a hash with keys being of the Symbol type as per the example above

:process_results

Indicates the client preference to receive a result or not, the SimpleRPC agent should not send a response at all if this is true.

Replies

As with requests the replies just build on the core MessageFormat and would be in the body of the standard message.

A typical rely would look like:

{:statuscode => 0
 :statusmsg  => "OK",
 :data       => {:message => "hello world"}}

:statuscode and :statusmsg

The statuscode and statusmsg are related and is used for error propagation through the collective.

These are the documented errors clients receive and will result in exceptions raised on the client in some cases.

The agent’s fail and fail! methods will manipulate these structures.

:data

This is a freeform variable for any data being returned by agents. Technically it can be anything but by SimpleRPC convention it’s a hash with keys being of type Symbol.

↑ Back to top