API

Notice

This document specifies the protocol used by the splonebox to communicate with clients. The protocol is based on msgpack-rpc.

Requests

All 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 responses are based on the msgpack-rpc response type:

[1, request_msgid, error, result]

Error responses

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]

Register

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
			<api key>,
			<plugin name>,
			<description>,
			...
		],
		[                          # List of functions
			[                      # Function description 
				<function name>,
				<function descripton>,
				[<arg (="")>, <arg(=0)>] # Some Value is given to identify the type
			],
			[
				...
      			]
		]

	]
]

Valid call

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)

Run

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
	   <call id>
	  ],
		<function name>,
		[                          # Functions
			<arg1>,
			<arg2>,
			...
		]
	]
]

Valid call

If the run call was successful the following message should be returned by the executing client:

[1 , request_msgid, nil, [call_id]]

Result [WIP]

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>
    ]
  ]
]