category: Architecture

Document updated for protocol v2

This article describes system requests in Stormancer. System requests are messages sent by clients to a Stormancer node that will be handled by the cluster itself and not by the application.

System requests enable the clients to retrieve informations about a scene, connect or disconnect to and from them or update metadata associated with their connection.

Most system requests are composed of: - 1 message from the client to the server containing the request operation Id, the request id and a parameter object. - 1 or more response messages containing the request Id and a response object. - 1 completed or error message

Message content

Parameters and response objects are serialized using the msgPack format.

All strings are UTF8 encoded.

Header

Requests

| Size    | 1                 | 1            | 2          | ...
| Content | ID_SYSTEM_REQUEST | operation id | request id | Msgpack encoded parameter

The request id must be unique for a given client and will be provided in the header of the response messages.

Response message

The server can issue one or several response messages. Most system requests generate a single response message.

| Size    | 1                       | 2          | ...
| Content | ID_REQUEST_RESPONSE_MSG | request id | msgpack encoded object

Completed message

Completed messages can sometime be received before response messages. If that happen, check the "has messages" flag and wait for the response message if its value is different from '0'.

| Size    | 1                            | 2          | 1
| Content | ID_REQUEST_RESPONSE_COMPLETE | request id | has responses ?

Error message

The request observable can emit error events if necessay. In this case, a response of type ID_REQUEST_RESPONSE_ERROR will be received by the client for the request, with a ClientException object as packet data.

| Size    | 1                            | 2          | ...
| Content | ID_REQUEST_RESPONSE_ERROR | request id | msgpack encoded ClientException object

ClientException
{
   Id:string, //Unique id of the error, can be used to get more informations in the server logs for instance.
   Msg:string //Message of the error.
}

Operations

enum SystemRequestIDTypes : byte
{
    ID_GET_SCENE_INFOS = 136,
    ID_CONNECT_TO_SCENE = 134,
    ID_SET_METADATA = 0,
    ID_READY = 1,
    ID_DISCONNECT_FROM_SCENE = 135,

}

Update connection metadata

Updates the client metadata on the server

Parameter

This operation takes a map of string:string metadata as a parameter. This map will replace the current client metadata on the server.

[
  key:string => value:string
]

Returns

The operation returns nothing.

Get scene informations

This operation retrieves informations about the target scene. The informations include scene metadata, the list of the available route, the handle for each routes and their metadata.

All these steps are done by making a Get scene infos Request (ID_GET_SCENE_INFOS)

Parameter

 {
   Token: byte[], //The token obtained from the API to authenticate the resquest. It contains the id of the target scene.
   Metadata: (key:string=>value:string), //The client metadata
 }

The metadata are read by the server only once when connecting to the first scene. They can be safely ignored afterwards.

Returns

{
  Id:string, //Id of the scene.
  Metadata:(key:string=>value:string),
  Routes : [{ //List of Route objects
               Id:string, //Id of the route.
               Handle:ushort, //Handle of the route.
               Metadata: (key:string=>value:string) //Metadata associated with the route.
           }]
  SelectedSerializer:string //The serializer to use to communicate with the scene code.
}

Connect to a scene

This operation connects the provided scene client handle to the target remote scene identified by the connection token and inform the scene host of the routes available on the client.

The scene host can accept or refuse the connection.

Parameter

{
  Token:byte[] //The connection token
  Routes: [{ //List of route objects available on the client for the scene.
               Id:string, //Id of the route.
               Handle:ushort, //Handle of the route.
               Metadata: (key:string=>value:string) //Metadata associated with the route.
          }]
  SceneMetadata : [string:string] //Metadata associated with the client scene.
}

Returns

The handle of the connection to the scene.

{
   SceneHandle:byte
   RouteMapping: [string:ushort] //Mappings of routes in the scene.
}

Disconnect from a scene

Disconnects the client from a scene using its handle.

Parameter

Handle:byte

Returns

{
   Handle: byte
   Reason: string
}