diff options
Diffstat (limited to 'protocol.txt')
| -rw-r--r-- | protocol.txt | 63 |
1 files changed, 63 insertions, 0 deletions
diff --git a/protocol.txt b/protocol.txt new file mode 100644 index 0000000..8fe08f1 --- /dev/null +++ b/protocol.txt @@ -0,0 +1,63 @@ +(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 TQDataStream 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. + +================================================================================== +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] + +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 <TQ_UINT32 'Type ID'> +SERV <TQ_UINT32 'Service ID'> +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. + +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: +TQ_UINT32 Type ID +TQValueList<TQ_UINT32> Service IDs +TQString Description +TQ_UINT32 Total station count of this type +TQ_UINT32 Number of stations of this type in use + +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 type ID and description. Type IDs do not need to be universally unique, but must remain constant for a given connection after a LIST command. Subsequent commands may alter the Type ID mappings. + +BIND <TQ_UINT32 'Type ID'>: +Connects to a specified laboratory station +If a station with the specified Type ID 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 Type ID is not available, the server must respond with a string containing the case-sensitive text "ERRUNAVAL" and must re-enter command mode. + +Example: BIND 5 + +SERV <TQ_UINT32 'Service ID'> +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. 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 4000 + +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.
\ No newline at end of file |