X-Git-Url: https://git.tokkee.org/?p=sysdb.git;a=blobdiff_plain;f=src%2Finclude%2Ffrontend%2Fproto.h;h=c006c49afef15284c98d7da909b5654c8217952b;hp=fd78c26cf61833bd5ac07cc40a17217982c71fdb;hb=ee8df3b190c2eb49e460dcf03f81288a5d825c39;hpb=4215d1d8c69367c1d43bed9d39d428a92b329a92

diff --git a/src/include/frontend/proto.h b/src/include/frontend/proto.h
index fd78c26..c006c49 100644
--- a/src/include/frontend/proto.h
+++ b/src/include/frontend/proto.h
@@ -32,22 +32,166 @@
 extern "C" {
 #endif
 
+/*
+ * The SysDB frontend protocol is based on messages being passed between the
+ * client and the server. Each message includes a header containing the
+ * message type which is usually a status or command code, the length of the
+ * message not including the header, and the message body. The content of the
+ * message body depends on the message type. Both, the message type and length
+ * are stored in an unsigned 32bit integer in network byte-order.
+ *
+ *                  1               3               4               6
+ *  0               6               2               8               4
+ * +-------------------------------+-------------------------------+
+ * | message type                  | message length                |
+ * +-------------------------------+-------------------------------+
+ * | message body ...
+ *
+ */
+
 /* status codes returned to a client */
 typedef enum {
+	/*
+	 * CONNECTION_OK:
+	 * Indicates that a command was successful. The message body will usually
+	 * be empty but may contain a string providing unformatted information
+	 * providing more details.
+	 *
+	 * 0               32              64
+	 * +---------------+---------------+
+	 * | message type  | length        |
+	 * +---------------+---------------+
+	 * | optional status message ...   |
+	 */
 	CONNECTION_OK = 0,
-	CONNECTION_ERROR
+
+	/*
+	 * CONNECTION_DATA:
+	 * Indicates that a data query was successful. The message body will
+	 * contain the type of the data and the result encoded as a JSON string.
+	 * The type is the same as the command code of the respective command (see
+	 * below) and is stored as an unsigned 32bit integer in network
+	 * byte-order. The result may be empty (but the type is still included).
+	 *
+	 * 0               32              64
+	 * +---------------+---------------+
+	 * | message type  | length        |
+	 * +---------------+---------------+
+	 * | result type   | result ...    |
+	 * +---------------+               |
+	 * | ...                           |
+	 */
+	CONNECTION_DATA,
+
+	/*
+	 * CONNECTION_ERROR:
+	 * Indicates that a command has failed. The message body will contain a
+	 * string describing the error.
+	 *
+	 * 0               32              64
+	 * +---------------+---------------+
+	 * | message type  | length        |
+	 * +---------------+---------------+
+	 * | error message ...             |
+	 */
+	CONNECTION_ERROR,
+
+	/*
+	 * CONNECTION_LOG:
+	 * Indicates an asynchronous log message. The message body will contain
+	 * the message string providing informational or warning logs. Log
+	 * messages may be sent to the client any time.
+	 *
+	 * 0               32              64
+	 * +---------------+---------------+
+	 * | message type  | length        |
+	 * +---------------+---------------+
+	 * | log message ...               |
+	 */
+	CONNECTION_LOG,
 } sdb_conn_status_t;
 
 /* accepted commands / state of the connection */
 typedef enum {
-	/* connection handling */
+	/*
+	 * CONNECTION_IDLE:
+	 * This is an internal state used for idle connections.
+	 */
 	CONNECTION_IDLE = 0,
+
+	/*
+	 * CONNECTION_PING:
+	 * Check if the current connection is still alive. The server will reply
+	 * with CONNECTION_OK if it was able to handle the command.
+	 */
 	CONNECTION_PING,
+
+	/*
+	 * CONNECTION_STARTUP:
+	 * Setup of a client connection. The message body shall include the
+	 * username of the user contacting the server. The server may then send
+	 * further requests to the client for authentication (not implemented
+	 * yet). Once the setup and authentication was successful, the server
+	 * replies with CONNECTION_OK. Further information may be requested from
+	 * the server using special messages specific to the authentication
+	 * method. The server does not send any asynchronous messages before
+	 * startup is complete.
+	 */
 	CONNECTION_STARTUP,
 
-	/* querying */
+	/*
+	 * Querying the server. On success, the server replies with
+	 * CONNECTION_DATA.
+	 *
+	 * The command codes listed here are used, both, for sending a query to
+	 * the server and to indicate the response type from a query in a DATA
+	 * message.
+	 */
+
+	/*
+	 * CONNECTION_QUERY:
+	 * Execute a query in the server. The message body shall include a single
+	 * query command as a text string. Multiple commands are ignored by the
+	 * server entirely.
+	 */
 	CONNECTION_QUERY,
+
+	/*
+	 * CONNECTION_FETCH:
+	 * Execute the 'FETCH' command in the server. The message body shall
+	 * include the hostname of the host to be retrieved.
+	 */
+	CONNECTION_FETCH,
+
+	/*
+	 * CONNECTION_LIST:
+	 * Execute the 'LIST' command in the server.
+	 */
 	CONNECTION_LIST,
+
+	/*
+	 * CONNECTION_LOOKUP:
+	 * Execute the 'LOOKUP' command in the server. The message body shall
+	 * include the conditional expression of the 'MATCHING' clause.
+	 */
+	CONNECTION_LOOKUP,
+
+	/*
+	 * CONNECTION_TIMESERIES:
+	 * Execute the 'TIMESERIES' command in the server. This command is not yet
+	 * supported on the wire. Use CONNECTION_QUERY instead.
+	 */
+	CONNECTION_TIMESERIES,
+
+	/*
+	 * Command subcomponents.
+	 */
+
+	/*
+	 * CONNECTION_EXPR:
+	 * A parsed expression. Only used internally.
+	 */
+	CONNECTION_EXPR,
 } sdb_conn_state_t;
 
 #ifdef __cplusplus