src/include/frontend/proto.h

   1 /*
   2  * SysDB - src/include/frontend/proto.h
   3  * Copyright (C) 2013 Sebastian 'tokkee' Harl <sh@tokkee.org>
   4  * All rights reserved.
   5  *
   6  * Redistribution and use in source and binary forms, with or without
   7  * modification, are permitted provided that the following conditions
   8  * are met:
   9  * 1. Redistributions of source code must retain the above copyright
  10  *    notice, this list of conditions and the following disclaimer.
  11  * 2. Redistributions in binary form must reproduce the above copyright
  12  *    notice, this list of conditions and the following disclaimer in the
  13  *    documentation and/or other materials provided with the distribution.
  14  *
  15  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  16  * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  17  * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  18  * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR
  19  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
  20  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
  21  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
  22  * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
  23  * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
  24  * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
  25  * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  26  */
  27
  28 #ifndef SDB_FRONTEND_PROTO_H
  29 #define SDB_FRONTEND_PROTO_H 1
  30
  31 #ifdef __cplusplus
  32 extern "C" {
  33 #endif
  34
  35 /*
  36  * The SysDB frontend protocol is based on messages being passed between the
  37  * client and the server. Each message includes a header containing the
  38  * message type which is usually a status or command code, the length of the
  39  * message not including the header, and the message body. The content of the
  40  * message body depends on the message type. Both, the message type and length
  41  * are stored in an unsigned 32bit integer in network byte-order.
  42  *
  43  * Any strings in the message body may not include a zero byte.
  44  *
  45  *                  1               3               4               6
  46  *  0               6               2               8               4
  47  * +-------------------------------+-------------------------------+
  48  * | message type                  | message length                |
  49  * +-------------------------------+-------------------------------+
  50  * | message body ...
  51  *
  52  */
  53
  54 /* status codes returned to a client */
  55 typedef enum {
  56         /*
  57          * Generic status and log messages.
  58          */
  59
  60         /*
  61          * SDB_CONNECTION_OK:
  62          * Indicates that a command was successful. The message body will usually
  63          * be empty but may contain a string providing unformatted information
  64          * providing more details.
  65          *
  66          * 0               32              64
  67          * +---------------+---------------+
  68          * | OK            | len(msg)      |
  69          * +---------------+---------------+
  70          * | optional status message ...   |
  71          */
  72         SDB_CONNECTION_OK = 0,
  73
  74         /*
  75          * SDB_CONNECTION_ERROR:
  76          * Indicates that a command has failed. The message body will contain a
  77          * string describing the error.
  78          *
  79          * 0               32              64
  80          * +---------------+---------------+
  81          * | ERROR         | len(msg)      |
  82          * +---------------+---------------+
  83          * | error message ...             |
  84          */
  85         SDB_CONNECTION_ERROR,
  86
  87         /*
  88          * SDB_CONNECTION_LOG:
  89          * Indicates an asynchronous log message. The message body will contain
  90          * the log priority (see utils/error.h) and message. Log messages may be
  91          * sent to the client any time.
  92          *
  93          * 0               32              64
  94          * +---------------+---------------+
  95          * | LOG           | length        |
  96          * +---------------+---------------+
  97          * | log priority  | log message   |
  98          * +---------------+               |
  99          * | ...                           |
 100          */
 101         SDB_CONNECTION_LOG,
 102
 103         /*
 104          * Query-result specific messages.
 105          */
 106
 107         /*
 108          * SDB_CONNECTION_DATA:
 109          * Indicates that a data query was successful. The message body will
 110          * contain the type of the data and the result encoded as a JSON string.
 111          * The type is the same as the command code of the respective command (see
 112          * below) and is stored as an unsigned 32bit integer in network
 113          * byte-order. The result may be empty (but the type is still included) if
 114          * the query did not return any result. The type and the result message
 115          * are empty on empty commands.
 116          *
 117          * 0               32              64
 118          * +---------------+---------------+
 119          * | DATA          | length        |
 120          * +---------------+---------------+
 121          * | result type   | result ...    |
 122          * +---------------+               |
 123          * | ...                           |
 124          */
 125         SDB_CONNECTION_DATA = 100,
 126 } sdb_conn_status_t;
 127
 128 /* accepted commands / state of the connection */
 129 typedef enum {
 130         /*
 131          * SDB_CONNECTION_IDLE:
 132          * This is an internal state used for idle connections.
 133          */
 134         SDB_CONNECTION_IDLE = 0,
 135
 136         /*
 137          * SDB_CONNECTION_PING:
 138          * Check if the current connection is still alive. The server will reply
 139          * with SDB_CONNECTION_OK and an empty message body if it was able to
 140          * handle the command.
 141          *
 142          * 0               32              64
 143          * +---------------+---------------+
 144          * | PING          | 0             |
 145          * +---------------+---------------+
 146          */
 147         SDB_CONNECTION_PING,
 148
 149         /*
 150          * SDB_CONNECTION_STARTUP:
 151          * Setup of a client connection. The message body shall include the
 152          * username of the user contacting the server. The server may then send
 153          * further requests to the client for authentication (not implemented
 154          * yet). Once the setup and authentication was successful, the server
 155          * replies with SDB_CONNECTION_OK. Further information may be requested
 156          * from the server using special messages specific to the authentication
 157          * method. The server does not send any asynchronous messages before
 158          * startup is complete.
 159          *
 160          * 0               32              64
 161          * +---------------+---------------+
 162          * | STARTUP       | len(username) |
 163          * +---------------+---------------+
 164          * | username ...                  |
 165          */
 166         SDB_CONNECTION_STARTUP,
 167
 168         /*
 169          * Querying the server. On success, the server replies with
 170          * SDB_CONNECTION_DATA.
 171          *
 172          * The command codes listed here are used, both, for sending a query to
 173          * the server and to indicate the response type from a query in a DATA
 174          * message.
 175          */
 176
 177         /*
 178          * SDB_CONNECTION_QUERY:
 179          * Execute a query in the server. The message body shall include a single
 180          * query command as a text string. Multiple commands are ignored by the
 181          * server entirely to protect against injection attacks.
 182          *
 183          * 0               32              64
 184          * +---------------+---------------+
 185          * | QUERY         | len(query)    |
 186          * +---------------+---------------+
 187          * | query string ...              |
 188          */
 189         SDB_CONNECTION_QUERY,
 190
 191         /*
 192          * SDB_CONNECTION_FETCH:
 193          * Execute the 'FETCH' command in the server. The message body shall
 194          * include the type and the identifier of the object to be retrieved.
 195          * Hosts are identified by their name. Other types are not supported yet.
 196          * The type is encoded as a 32bit integer in network byte-order.
 197          *
 198          * 0               32              64
 199          * +---------------+---------------+
 200          * | FETCH         | length        |
 201          * +---------------+---------------+
 202          * | object type   | identifier    |
 203          * +---------------+               |
 204          * | ...                           |
 205          */
 206         SDB_CONNECTION_FETCH,
 207
 208         /*
 209          * SDB_CONNECTION_LIST:
 210          * Execute the 'LIST' command in the server. The message body may include
 211          * the type of the objects to be listed, encoded as a 32bit integer in
 212          * network byte-order. The response includes all hosts and the respective
 213          * child objects. By default, all hosts are listed.
 214          *
 215          * 0               32              64
 216          * +---------------+---------------+
 217          * | LIST          | length        |
 218          * +---------------+---------------+
 219          * | [object type] |
 220          * +---------------+
 221          */
 222         SDB_CONNECTION_LIST,
 223
 224         /*
 225          * SDB_CONNECTION_LOOKUP:
 226          * Execute the 'LOOKUP' command in the server. The message body shall
 227          * include the type of the objects to look up and a string representing
 228          * the conditional expression of the 'MATCHING' clause. The type is
 229          * encoded as a 32bit integer in network byte-order.
 230          *
 231          * 0               32              64
 232          * +---------------+---------------+
 233          * | LOOKUP        | length        |
 234          * +---------------+---------------+
 235          * | object type   | matching      |
 236          * +---------------+               |
 237          * | clause ...                    |
 238          */
 239         SDB_CONNECTION_LOOKUP,
 240
 241         /*
 242          * SDB_CONNECTION_TIMESERIES:
 243          * Execute the 'TIMESERIES' command in the server. This command is not yet
 244          * supported on the wire. Use SDB_CONNECTION_QUERY instead.
 245          */
 246         SDB_CONNECTION_TIMESERIES,
 247
 248         /*
 249          * Command subcomponents.
 250          */
 251
 252         /*
 253          * SDB_CONNECTION_MATCHER:
 254          * A parsed matcher. Only used internally.
 255          */
 256         SDB_CONNECTION_MATCHER = 100,
 257
 258         /*
 259          * SDB_CONNECTION_EXPR:
 260          * A parsed expression. Only used internally.
 261          */
 262         SDB_CONNECTION_EXPR,
 263 } sdb_conn_state_t;
 264
 265 #ifdef __cplusplus
 266 } /* extern "C" */
 267 #endif
 268
 269 #endif /* ! SDB_FRONTEND_PROTO_H */
 270
 271 /* vim: set tw=78 sw=4 ts=4 noexpandtab : */
 272