Unreliable Module

Description

Unreliable module provides a Connection class, to which any other connection (inheriting from Communication::Connection) may upgrade to. Unreliable::Connection uses UDP as the transport layer, hence the name.

The Communication::Connection API exposes method Send, second boolean argument says whether the message has to be send in a reliable fashion (for fully reliable connections, like Http::Websocket, it has no meaning whatsoever). Unreliable::Connection uses UDP protocol to send messages marked as unreliable (meaning that it is permitted they will not reach other peer), and the underlying reliable connection (e.g. Http::Websocket) for other.

Unreliable::Connection uses underlying connection handshake for the upgrade process.

The scheme of Unreliable::Connection is composed of the scheme of underlying connection (e.g. "ws") prefixed with "ur", so the example URL for the unreliably-upgraded Websocket connection will be urws://tilia.man.poznan.pl:9000/sessions/test.

The handshake process goes in following steps:

  1. Unreliable module recognises the outgoing connection by the scheme (the side initiating the connection will be called the client side - in opposition to the server side)
  2. client binds a UDP socket on a arbitrarily chosen port (let it be C)
  3. client arbitrarily prepares a set of ports, from which server will choose one port to use (let it be P)
  4. client adds following headers to the underlying connection headers:
    X-Vitrall-Unreliable-Client-Port: C
    X-Vitrall-Unreliable-Server-Port-Proposition: P
    
  5. headers are included in the underlying protocol header and sent to the server
  6. server recognises the upgrade attempt by looking for headers X-Vitrall-Unreliable-*
  7. server tries to bind on one of the given ports from set P (let it be S)
  8. server connects the socket to port C
  9. server adds following header to the response headers:
    X-Vitrall-Unreliable-Server-Port: S
    
  10. client decodes the header and connects it's socket (previously binded to C) to port S.

The IP addresses used throughout the process are the same as the IP addresses used by the underlying protocol.

The set of ports (X-Vitrall-Unreliable-Server-Port-Proposition header) conforms to the following grammar:

set = interval intervals ;
intervals = ; 
intervals = "," intervals ;
interval = integer ;
interval = integer "-" integer ;

Following example contains 64 ports in total:

2000-2010,2015,9000,9050-9100