.. include:: alias.rst

.. _master_rpc_protocol:

RaceCom Master Protocol
=======================

This document describes the RPC API of the RaceCom master including
the data serialization format used in these RPC calls.

The RaceCom master is based on ZeroMQ with a simple data binary format
to encode remote procedure calls and the corresponding result objects

Data Serialization Format
-------------------------

The data format used for RPC request and response objects is as follows:

.. code-block:: none

   <identifier> [<field> ...]

The identifier is a single string indicating the type of the encoded
message. The message is encoded with all fields just stored
subsequently. The data is not aligned and the structure of the message
is not encoded in the field data block. All data is encoded in big
endian and all messages only consist of the following data types:

- string: Strings are encoded as follows:

  .. code-block:: none

     <uint64> [<uint8> ...]
   
  The first field is a 64bit unsigned integer containing the length of
  the string. The rest are characters encoded in Unicode.

- int: 32-bit integers, encoded in big endian.

- list: Lists are encoded similar to strings with a 64-bit unsigned
  int field indicating the number of elements followed by all elements
  in a sequence.

Request and Response Data Types
-------------------------------

This section documents all Master request and response types. The
first field always is a string identifying the encoded data type.

RegisterService
```````````````

.. code-block:: none

   "registerService"
   <string> // service name

UnregisterService
`````````````````

.. code-block:: none

   "unregisterService"
   <int32> // service id

RegisterOperation
`````````````````

.. code-block:: none

   "registerOperation"
   <int32> // service id
   <string> // operation name
   <string> // request type
   <string> // result type
   <string> // error type
   <string> // ZMQ url of the operation responder

RegisterEvent
`````````````

.. code-block:: none

   "registerEvent"
   <int32> // service id
   <string> // event name
   <string> // event type
   <string> // ZMQ url of the event published

ListServices
````````````

.. code-block:: none

   "listServices"

ListOperations
``````````````

List all operations of a given service.

.. code-block:: none

   "listOperations"
   <string> // service name

ListEvents
``````````
List all events of a given service.

.. code-block:: none

   "listEvents"
   <string> // service name


ServiceIdResponse
`````````````````

.. code-block:: none

   "serviceId"
   <int32> // service id

NoResponse
``````````

.. code-block:: none

   "nothing"

ErrorResponse
`````````````

.. code-block:: none

   "error"
   <string> // error message

ServiceListResponse
```````````````````
.. code-block:: none

   "serviceList"
   [<string>] // list of service names

OperationListResponse
`````````````````````
.. code-block:: none

   "operationList"
   [Operation] // list of operations

Eeach list element ``Operation`` is encoded as follows:

.. code-block:: none

   <string> // name of the operation
   <string> // request type
   <string> // result type
   <string> // error type
   <string> // ZMQ address of the operation

EventListResponse
`````````````````
.. code-block:: none

   "eventList"
   [Event] // list of events

Eeach list element ``Event`` is encoded as follows:

.. code-block:: none

   <string> // name of the event
   <string> // event type
   <string> // ZMQ address of the event

Remote Procedure Calls
----------------------

The RaceCom master runs on a single ZeroMQ ``Rep`` socket. Requests
and responses are in a binary format according to the data
serialization format explained above. The following types can be used
for making request. The list also documents all possible responses.

* ``RegisterService`` -> ``ServiceIdResponse`` or ``ErrorResponse``
* ``UnregisterService`` -> ``NoResponse`` or ``ErrorResponse``
* ``RegisterOperation`` -> ``NoResponse`` or ``ErrorResponse``
* ``RegisterEvent`` -> ``NoResponse`` or ``ErrorResponse``
* ``ListServices`` -> ``ServiceListResponse``
* ``ListOperations`` -> ``OperationListResponse`` or ``ErrorResponse``
* ``ListEvents`` -> ``EventListResponse`` or ``ErrorResponse``