Added mcollective 2.3.1 package

[packages/trusty/mcollective.git] / website / simplerpc / messageformat.md

diff --git a/website/simplerpc/messageformat.md b/website/simplerpc/messageformat.md
new file mode 100644 (file)
index 0000000..9fbf011
--- /dev/null
+++ b/website/simplerpc/messageformat.md
@@ -0,0 +1,92 @@
+---
+layout: default
+title: SimpleRPC Message Format
+---
+[MessageFormat]: ../reference/basic/messageformat.html
+[ErrorCodes]: clients.html#dealing-with-the-results-directly
+
+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:
+
+{% highlight ruby %}
+{:agent           => "echo",
+ :action          => "echo",
+ :caller          => "cert=rip",
+ :data            => {:message => "hello world"},
+ :process_results => true}
+{% endhighlight %}
+
+This structure will be sent as the _:body_ of the core message, you might create
+this request using the command below:
+
+{% highlight ruby %}
+  e = rpcclient("echo")
+  e.echo(:message => "hello world")
+{% endhighlight %}
+
+## :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:
+
+{% highlight ruby %}
+{:statuscode => 0
+ :statusmsg  => "OK",
+ :data       => {:message => "hello world"}}
+{% endhighlight %}
+
+## :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][ErrorCodes] 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.