User-Client Communication

Warning

The communication used between the user app and client app is not part of the main Fairdice protocol (which is concerned solely with the on the wire protocol between client and server).

The user app and client app might be implemented as a single piece of software. The user app might call a client app as a command line call, be compiled against it, or communicate with it over tcp/ip (possibly even with the client on a seperate machine, using ssh tunnels, vpns and what have you).

The following, then, is specific to the original frdi_client app that was implemented as a test of the main protocol.

Terminology

For each Client app there may be connected to it multiple User apps.

For each User-Client connection, there may be multiple Server apps; one Client-Server connections for each Host app the User connects to via this Client (and a Server).

For each Client-Server connection, there may be multiple Games.

For each Game there are several stages:

Initialisation - setting up the game
Randomisation - getting the inputs
Generation - producing the output
Verification - checking for fraud

For each Stage there may be multiple messages sent back and forth between the User app and Client app.

Syntax

################
#              #
#  Section 1   #
#              #
################
the easy bits - what to do once the
user-client-server-host connection is up, validated, etc.
and the user wants to start playing a specific game on the
host.

U->C   : G <gamestr> : play
C->U   : G <gamestr> : no
C->U   : G <gamestr> : yes <n>    # your player number
C->U   : G <gamestr> : started
C->U   : G <gamestr> : outcome <outcome>
C->U   : G <gamestr> : finish fair
C->U   : G <gamestr> : finish fail
C->U   : G <gamestr> : finish fraud


################
#              #
#  Section 2   #
#              #
################
optional helpful bits.  valid at any time

x->y   : <some message>
y->x   : U <some message>
or
y->x   : U null
(basically says "I'm confused!")

x->y   : D is <description>
or
x->y   : D request
y->x   : D is <description>
or
y->x   : D null

U->C   : R <size> <data>
sends data to the remote host

C->S   : R <size> <data>
data from the remote host

x->y  :  L opening
y->x  :  L opened

x->y  :  L closing
y->x  :  L closed

x->y  :  K null
no action required

x->y  :  K ping request <n>
y->x  :  K ping response <n>
pings the client/user

x->y  :  K time <t>
no action required

x->y  :  K time
y->x  :  K time <t>


################
#              #
#  Section 3   #
#              #
################
getting to the point where you can play
(note there is currently no versioning of
 this user-client stuff.)

U->C    : F I am user <userstr> : secret <secret>
U->C    : F connect me to S <serverstr> : H <hoststr>
C->U    : F yes
C->U    : F no <message>