remotelaboratory/protocol.txt

(c) 2012 Timothy Pearson, Raptor Engineering
Licensed under the GPL v2

==================================================================================
Overview
==================================================================================

The remote laboratory architecture is highly modularized, with the client containing multiple modules, each of which connects directly to a master server.  The server similarly consists of a master control server, which manages connections to backend servers, each providing access to a particular laboratory service.  Multiple backend servers may be required to access a particular set of laboratory resources, referred to herein as a laboratory station.

The client container itself must initiate the first connection and negotiate access to the requested type of laboratory resources, including prompting the user with a list of available resource types.  Once the client container has established a connection, the client modules may connect to the master server and will receive stream access to the appropriate backend server daemon.  If a client module attempts to connect to the master server when a container connection is not open, the server must reject the connection.

Negotation and master control protocols must use a TQDataStream in printable (7-bit) mode to serialize and deserialize commands and responses, while client modules and their associated server daemons may choose to implement any binary or text-based communication protocol required for the specific application.  The use of TQDataStream is strongly suggested where possible to maintain codebase consistency.

Due to the block encryption used by Kerberos, stream block delimeters are required at the transfer layer.  The delimeter must be a single newline character, 0xD ('\n'), and will indicate the end of a block has been reached; therefore, the block is ready for decryption and processing.  All block transfers must use Base64 encoding, and the encoded block text must not contain the newline character.

Furthermore, to ensure robust command processing, the master server utilizes a frame-based protocol, with a single character of value 255 indicating the end of a frame.  The value 255 is therefore reserved and must not appear in data transmitted to or from the master server, except when used to indicate the end of a frame.  The three-character abbreviation EOF will be used to refer to this frame termination character within this document.

==================================================================================
Master Server
==================================================================================

The master server acts as a semi-transparent communications relay between the client and any requested backend servers.  It must decrypt all incoming client data and reencrypt it for transmission to the appropriate backend server over the backend link.

On initial connection from the client container, the master server must negotiate a successful Kerberos connection.  Once this connection is established, the server must transmit the following data types:
TQ_UINT32 [magic number]
TQ_UINT32 [protocol version]
EOF

The client may terminate the connection at any time, or provide invalid data to the server.  If the server loses connection sync with the client or receives invalid data from the client, it must gracefully terminate the connection without interruption to connections from other users.  If the client container connection is terminated, all other service connections for that user must also be terminated.

After initial negotiation, the server must enter command mode.  In this mode the server expects to receive a command string.  The following commands are currently supported:
LIST
BIND <StationType 'Type ID'>
SERV <TQString    'Client Library Name'>
QUIT

If an invalid command is specified, the server should respond with a string containing the case-sensitive text "ERRINVCMD".

The expected actions and/or data transmission/reception on receipt of a valid command are detailed below.  Each value returned by the server must be followed with an EOF character.

LIST:
Returns a list of available laboratory stations
The server should return a TQValueList<StationType>, where StationType consists of the following types for each laboratory station:
<this is still in flux, see tqtrla.h for current data structure(s)>

Descriptions should be constructed from station service type flags as known to the master server, and multiple stations with identical resources should be consolidated to one station type ID and description.  Station type IDs do not need to be universally unique, but must not conflict with other station type IDs.  Subsequent commands may alter the station type ID mappings.

Example: LIST EOF

BIND <StationType 'Type ID'>:
Connects to a specified laboratory station
If a station with the specified Service ID list is available, the server must mark that station as in use by the authenticated user, must return the case-sensitive text "OK", and should block all commands other than QUIT.  If a station with the specified Service ID list is not available, the server must respond with a string containing the case-sensitive text "ERRUNAVAL" and must re-enter command mode.  If the specified user is already connected to a laboratory station, the server must return the case-sensitive text "ERRPREVCN", and should block all commands other than QUIT.

Example: BIND EOF
         StationType EOF

SERV <TQString 'Client Library Name'>
Requests a connection to the specified backend server on the laboratory station
If BIND was previously commanded on this connection, the server must respond with a string containing the case-sensitive text "ERRINVCMD".  If no station has been reserved for this user via a call to BIND on an active connection, the server must respond with a string containing the case-sensitive text "ERRNOCONN".  If the backend server is not available, i.e. a connection attempt or attempts have failed to establish a connection, the server should respond with the string "ERRNOTAVL" and must close the client connection.  If the backend service is not available in the active laboratory workspace, the server should respond with the string "ERRNOSERV" and must close the client connection.  Otherwise, the server must return a string containing the case-sensitive text "OK" and then immediately enter binary pass-through mode between the backend server and the client.

Example: SERV EOF
         libremotelab_fpgaviewer EOF

TSTP:
Returns a long long value containing the termination timestamp, if set
If an administrator has enabled automatic termination of the client's session, a UNIX timestamp with the exact termination time must be returned.  If automatic termination has not been enabled, the server must return zero.

QUIT:
Gracefully terminates the connection.
The server should return the case-sensitive text "OK" and must immediately close all active connections for the current user.

Example: QUIT EOF

==================================================================================
Backend Server
==================================================================================

On initial connection from the client container, the master server must negotiate a successful Kerberos connection.  Once this connection is established, the server must transmit a string containing the case-sensitive text "OK", followed by an EOF character.  The server has now fully established a secure bidirectional channel to the client and may proceeed to use the channel for any purpose.  If the server wishes to reject the connection, for example due to a hardware failure, it must transmit a string containing the case-sensitive text "ERRNOTAVL", followed by an EOF character, after which the server should close the client connection.