category: Specifications

Draft

Goals

Stormancer is designed with small messages in mind, ideally smaller than the MTU. However, developers may often want to transfer bigger payload (gameplay/map definition, assets), and even sometime stream realtime binary content over long period of time (voice, files or video). These use cases are not properly handled by the core functionalities of Stormancer. The streaming plugin works at an higher level to add support for binary streaming to all the message sending APIs.

The streaming plugin supports: - Switching to streaming when the message size becomes higher than a fixed value (currently 1024 bytes) - Sending chunk of the stream to the remote peer by calling the flush method - Automatic Flush when 1024 bytes are accumulated by the stream object. - Closing a stream - ReadAsync method to asynchronously wait for the arrival of a new packet.

It also adds the Stream OpenStream(string route, PacketReliability reliability, PacketPriority priority) method to create a stream instance that writes to a remote route.

Failing to close a stream can cause resource leaks, in particular when using the new OpenStream API. When using the old Send API, streams are automatically closed when the 'writer' method completes.

Implementation

The streaming plugin change the stream object provided as parameter to "writer" methods to another object that will cut the data written to the it into smaller packets which can be efficiently sent over the network. When a message bigger than 1024 bytes is written to the stream, the plugin will immediately send the first 1024 bytes as a packet to the remote peer along a "start stream" header . Then whenever 1024 bytes are accumulated or the flush method is called, a new packet is sent along a "stream chunk" header. When the stream is closed, a "close stream" message is sent, at which point it's not possible to add new data to the stream anymore.

Streams are identified using a 1 byte id (255 excluded) unique to the sending peer (stream id). This means that a peer can only maintain 255 simultaneous outbound streams to a single remote peer.

The streaming protocol reserves the route handles with 254 or 255 as the first byte.

Start stream message

{scene handle (1 byte)} {magic start stream route handle : 255 255 ) {stream id (1 byte)} {route handle (2 byte) } {content}

The start stream message suffers from a 3 bytes overhead compared to normal route packets.

Stream section message

{scene handle (1 byte)}{magic stream section route handle : 255 (stream id) } { content }

Stream section messages don't suffer from any overhead compared to normal route packets.

Close stream message

{scene handle(1 byte)}{ magic close stream route handle : 254 (stream id)}