website/simplerpc/messageformat.md

   1 ---
   2 layout: default
   3 title: SimpleRPC Message Format
   4 ---
   5 [MessageFormat]: ../reference/basic/messageformat.html
   6 [ErrorCodes]: clients.html#dealing-with-the-results-directly
   7
   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.
  11
  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].
  16
  17 # Requests
  18
  19 A basic SimpleRPC message can be seen below:
  20
  21 {% highlight ruby %}
  22 {:agent           => "echo",
  23  :action          => "echo",
  24  :caller          => "cert=rip",
  25  :data            => {:message => "hello world"},
  26  :process_results => true}
  27 {% endhighlight %}
  28
  29 This structure will be sent as the _:body_ of the core message, you might create
  30 this request using the command below:
  31
  32 {% highlight ruby %}
  33   e = rpcclient("echo")
  34   e.echo(:message => "hello world")
  35 {% endhighlight %}
  36
  37 ## :agent
  38
  39 Records the agent that this message is targetted at.
  40
  41 ## :action
  42
  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
  45 the SimpleRPC agent
  46
  47 ## :caller
  48
  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.
  53
  54 ## :data
  55
  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
  59
  60 ## :process_results
  61
  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.
  64
  65 # Replies
  66
  67 As with requests the replies just build on the core [MessageFormat] and would be
  68 in the body of the standard message.
  69
  70 A typical rely would look like:
  71
  72 {% highlight ruby %}
  73 {:statuscode => 0
  74  :statusmsg  => "OK",
  75  :data       => {:message => "hello world"}}
  76 {% endhighlight %}
  77
  78 ## :statuscode and :statusmsg
  79
  80 The statuscode and statusmsg are related and is used for error propagation
  81 through the collective.
  82
  83 These are the [documented errors clients receive][ErrorCodes] and will result
  84 in exceptions raised on the client in some cases.
  85
  86 The agent's _fail_ and _fail!_ methods will manipulate these structures.
  87
  88 ## :data
  89
  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
  92 type Symbol.