This document specifies the protocol used by the splonebox to communicate with clients. The protocol is based on msgpack-rpc.
All API requests are based on the msgpack-rpc request type:
[0, msgid, method, params]
All request expect a single response witch should be handled either by the core or by the clients. Responses may be errors or results carrying meta information.
All API responses are based on the msgpack-rpc response type:
[1, request_msgid, error, result]
Errors may occur at the server or at a remote client. Either way the response has this form:
[1, request_msgid, [errno, "Error description"], nil]
The register call is intended to be handled, if valid, by the core.:
[
msgid, # some random number.
type, # 0 Since it is a Request Type
method, # "register" for obvious reasons
[
[ # Metadata
<plugin name>,
<description>,
...
],
[ # List of functions
[ # Function description
<function name>,
<function descripton>,
[<arg (="")>, <arg(=0)>] # Some Value is given to identify the type
],
[
...
]
]
]
]
If the register call was successful the following message should be returned by the core:
[1 , request_msgid, nil, []]
(There might be some information to respond in the future. [] is currently a placeholder)
This call returns the registered plugins:
[
msgid, # some random number.
type, # 0 Since it is a Request Type
method, # "getregistered"
[]
]
[
1 , # since it's a respone
msgid, # echoing request id
nil, # no error
[# list of registered plugins
[ # Metadata
<plugin ID>,
<plugin name>,
<description>,
...
],
[ # List of functions
[ # Function description
<function name>,
<function descripton>,
[<arg (="")>, <arg(=0)>]
],
[ # next function of plugin
...
]
],
... # next plugin
]
A run call is verified by the core and forwarded to the corresponding client. [WIP] A call identifier should be generated by the server and sent in the response to the executing client. The executing client sends 'nil' instead of the call_id and waits for the response to get the id.
[
msgid, # id of the request we are responding to
type, # 0 Since it is a Request Type (See :class: `Message`)
method, # "run" for obvious reasons
[
[ # Metadata
<target plugin key>,
<call id>
],
<function name>,
[ # Functions
<arg1>,
<arg2>,
...
]
]
]
Client1 doesn't know the 'call_id' yet. The targets identifier (plugin key) must be provided to allow multiple instances of one plug-in.
After validating the message, the core creates an unique 'call_id' and forwards the message to client2. To avoid redundancy the plugin's identifier (plugin key) is not set. (If the identifier is set, the message is considered invalid)
For response messages it is mandatory that client1 receives the 'call_id' specified by the core.
If the run call was successful the following message should be returned by the executing client:
[1 , request_msgid, nil, [call_id]]
A result call is sent by an executing client after an execution has terminated successfully.
[
0, # request
m_id, # random number
"result",
[
[
call_id # call id specified by the core @ run call
],
[
<result>
]
]
]
Terminates the execution of the run call which is identified by call_id
[
0, # request
m_id, # random number
"stop",
[
call_id # call id specified by the core @ run call
]
]