frontend, proto: Include object type in FETCH and LOOKUP messages.

[sysdb.git] / src / include / frontend / proto.h

diff --git a/src/include/frontend/proto.h b/src/include/frontend/proto.h
index 2e82738449cd6a50826e22648e0dcd735167fca4..e9001cbb413003b01e8a3ab745827e228eaab3fa 100644 (file)
--- a/src/include/frontend/proto.h
+++ b/src/include/frontend/proto.h
@@ -33,7 +33,7 @@ extern "C" {
 #endif
 
 /*
- * The SysDB frontend protocol is based messages being passed between the
+ * 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
@@ -51,10 +51,21 @@ extern "C" {
 
 /* status codes returned to a client */
 typedef enum {
+       /*
+        * Generic status and log messages.
+        */
+
        /*
         * CONNECTION_OK:
-        * Indicates that a command was successful. The message body will contain
-        * the result of the command (if any) encoded as a JSON string.
+        * 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,
 
@@ -62,16 +73,54 @@ typedef enum {
         * 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.
+        * the log priority (see utils/error.h) and message. Log messages may be
+        * sent to the client any time.
+        *
+        * 0               32              64
+        * +---------------+---------------+
+        * | message type  | length        |
+        * +---------------+---------------+
+        * | log priority  | log message   |
+        * +---------------+               |
+        * | ...                           |
         */
        CONNECTION_LOG,
+
+       /*
+        * Query-result specific messages.
+        */
+
+       /*
+        * 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) if
+        * the query did not return any result. The type and the result message
+        * are empty on empty commands.
+        *
+        * 0               32              64
+        * +---------------+---------------+
+        * | message type  | length        |
+        * +---------------+---------------+
+        * | result type   | result ...    |
+        * +---------------+               |
+        * | ...                           |
+        */
+       CONNECTION_DATA = 100,
 } sdb_conn_status_t;
 
 /* accepted commands / state of the connection */
@@ -95,13 +144,20 @@ typedef enum {
         * 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. No other messages may be sent to the server
-        * before this.
+        * 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 the server.
+        * 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.
         */
 
        /*
@@ -115,20 +171,27 @@ typedef enum {
        /*
         * CONNECTION_FETCH:
         * Execute the 'FETCH' command in the server. The message body shall
-        * include the hostname of the host to be retrieved.
+        * include the type and the identifier of the object to be retrieved.
+        * Hosts are identified by their name. Other types are not supported yet.
+        * The type is encoded as a 32bit integer in network byte-order.
         */
        CONNECTION_FETCH,
 
        /*
         * CONNECTION_LIST:
-        * Execute the 'LIST' command in the server.
+        * Execute the 'LIST' command in the server. The message body may include
+        * the type of the objects to be listed, encoded as a 32bit integer in
+        * network byte-order. The response includes all hosts and the respective
+        * child objects. By default, all hosts are listed.
         */
        CONNECTION_LIST,
 
        /*
         * CONNECTION_LOOKUP:
         * Execute the 'LOOKUP' command in the server. The message body shall
-        * include the conditional expression of the 'MATCHING' clause.
+        * include the type of the objects to look up and a string representing
+        * the conditional expression of the 'MATCHING' clause. The type is
+        * encoded as a 32bit integer in network byte-order.
         */
        CONNECTION_LOOKUP,
 
@@ -147,7 +210,7 @@ typedef enum {
         * CONNECTION_EXPR:
         * A parsed expression. Only used internally.
         */
-       CONNECTION_EXPR,
+       CONNECTION_EXPR = 100,
 } sdb_conn_state_t;
 
 #ifdef __cplusplus