category: Architecture

This document describes how Stormancer clients connect to scenes.

Obtaining a scene connection token

Connection tokens are signed base64 encoded strings that secure the connection of a client to a given scene. Such a token must be obtained beforehand by a client that is willing to connect to the scene.

If the target scene is public, the client can issue a call to the Get token web API. Any content in the request body will be appended to the token and signed, along with the content type. A server application will be able to access this data associated with the connection. Use this feature to send json or msgpack serialized user profile data for instance.

In the client libraries, this operation is performed by the client.GetPublicScene(string sceneId, object userData) method. User data is msgpack serialized.

If the target scene is private, calls to the get token api must be authenticated by an application level token to ensure that only trusted code can generate tokens.

Connection process

  1. Extract the network endpoints from the connection token
  2. Select an endpoint suitable for the best available transport (Raknet or websocket)
  3. Connect to the endpoint
  4. Update the connection metadata by sending an ID_SET_METADATA system request.
  5. Perform an ID_GET_SCENE_INFOS system request using the token to retrieve informations about the target scene.
  6. Set the serializer proposed by the system request response as default serializer, add the serializer metadata value then update the connection metadata.
  7. Register local route handlers.
  8. Send a ID_CONNECT_TO_SCENE system request that contains the local route handlers.
  9. Use the information returned by the request to complete initialization of the scene object (set scene handle and local route handles)