3 title: SimpleRPC Message Format
5 [MessageFormat]: ../reference/basic/messageformat.html
6 [ErrorCodes]: clients.html#dealing-with-the-results-directly
8 SimpleRPC has a specific message structure that builds on the core
9 [MessageFormat]. As such SimpleRPC is simply a plugin developed
10 ontop of The Marionette Collective rather than an integrated part.
12 The core messages has a _:body_ structure where agents and clients
13 can send any data between nodes and clients. All the SimpleRPC
14 structures below goes in this body. Filters, targets etc all use the
15 standard core [MessageFormat].
19 A basic SimpleRPC message can be seen below:
24 :caller => "cert=rip",
25 :data => {:message => "hello world"},
26 :process_results => true}
29 This structure will be sent as the _:body_ of the core message, you might create
30 this request using the command below:
34 e.echo(:message => "hello world")
39 Records the agent that this message is targetted at.
43 The action being called. As the core protocol has no concept of actions per
44 agent this provides the needed data to route the request to the right code in
49 The callerid initiating the request. This is redundant and might be removed
50 later since the core message format also includes this information - the core
51 did not always include it. Removing it will only break backwards compatability
52 with really old versions.
56 The data being sent to the SimpleRPC action as its _request_ structure,
57 technically this can be any data but by SimpleRPC convention this would be a
58 hash with keys being of the Symbol type as per the example above
62 Indicates the client preference to receive a result or not, the SimpleRPC agent
63 should not send a response at all if this is true.
67 As with requests the replies just build on the core [MessageFormat] and would be
68 in the body of the standard message.
70 A typical rely would look like:
75 :data => {:message => "hello world"}}
78 ## :statuscode and :statusmsg
80 The statuscode and statusmsg are related and is used for error propagation
81 through the collective.
83 These are the [documented errors clients receive][ErrorCodes] and will result
84 in exceptions raised on the client in some cases.
86 The agent's _fail_ and _fail!_ methods will manipulate these structures.
90 This is a freeform variable for any data being returned by agents. Technically
91 it can be anything but by SimpleRPC convention it's a hash with keys being of