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  *                  1               3               4               6
  44  *  0               6               2               8               4
  45  * +-------------------------------+-------------------------------+
  46  * | message type                  | message length                |
  47  * +-------------------------------+-------------------------------+
  48  * | message body ...
  49  *
  50  */
  51
  52 /* status codes returned to a client */
  53 typedef enum {
  54         /*
  55          * Generic status and log messages.
  56          */
  57
  58         /*
  59          * CONNECTION_OK:
  60          * Indicates that a command was successful. The message body will usually
  61          * be empty but may contain a string providing unformatted information
  62          * providing more details.
  63          *
  64          * 0               32              64
  65          * +---------------+---------------+
  66          * | message type  | length        |
  67          * +---------------+---------------+
  68          * | optional status message ...   |
  69          */
  70         CONNECTION_OK = 0,
  71
  72         /*
  73          * CONNECTION_ERROR:
  74          * Indicates that a command has failed. The message body will contain a
  75          * string describing the error.
  76          *
  77          * 0               32              64
  78          * +---------------+---------------+
  79          * | message type  | length        |
  80          * +---------------+---------------+
  81          * | error message ...             |
  82          */
  83         CONNECTION_ERROR,
  84
  85         /*
  86          * CONNECTION_LOG:
  87          * Indicates an asynchronous log message. The message body will contain
  88          * the log priority (see utils/error.h) and message. Log messages may be
  89          * sent to the client any time.
  90          *
  91          * 0               32              64
  92          * +---------------+---------------+
  93          * | message type  | length        |
  94          * +---------------+---------------+
  95          * | log priority  | log message   |
  96          * +---------------+               |
  97          * | ...                           |
  98          */
  99         CONNECTION_LOG,
 100
 101         /*
 102          * Query-result specific messages.
 103          */
 104
 105         /*
 106          * CONNECTION_DATA:
 107          * Indicates that a data query was successful. The message body will
 108          * contain the type of the data and the result encoded as a JSON string.
 109          * The type is the same as the command code of the respective command (see
 110          * below) and is stored as an unsigned 32bit integer in network
 111          * byte-order. The result may be empty (but the type is still included) if
 112          * the query did not return any result. The type and the result message
 113          * are empty on empty commands.
 114          *
 115          * 0               32              64
 116          * +---------------+---------------+
 117          * | message type  | length        |
 118          * +---------------+---------------+
 119          * | result type   | result ...    |
 120          * +---------------+               |
 121          * | ...                           |
 122          */
 123         CONNECTION_DATA = 100,
 124 } sdb_conn_status_t;
 125
 126 /* accepted commands / state of the connection */
 127 typedef enum {
 128         /*
 129          * CONNECTION_IDLE:
 130          * This is an internal state used for idle connections.
 131          */
 132         CONNECTION_IDLE = 0,
 133
 134         /*
 135          * CONNECTION_PING:
 136          * Check if the current connection is still alive. The server will reply
 137          * with CONNECTION_OK if it was able to handle the command.
 138          */
 139         CONNECTION_PING,
 140
 141         /*
 142          * CONNECTION_STARTUP:
 143          * Setup of a client connection. The message body shall include the
 144          * username of the user contacting the server. The server may then send
 145          * further requests to the client for authentication (not implemented
 146          * yet). Once the setup and authentication was successful, the server
 147          * replies with CONNECTION_OK. Further information may be requested from
 148          * the server using special messages specific to the authentication
 149          * method. The server does not send any asynchronous messages before
 150          * startup is complete.
 151          */
 152         CONNECTION_STARTUP,
 153
 154         /*
 155          * Querying the server. On success, the server replies with
 156          * CONNECTION_DATA.
 157          *
 158          * The command codes listed here are used, both, for sending a query to
 159          * the server and to indicate the response type from a query in a DATA
 160          * message.
 161          */
 162
 163         /*
 164          * CONNECTION_QUERY:
 165          * Execute a query in the server. The message body shall include a single
 166          * query command as a text string. Multiple commands are ignored by the
 167          * server entirely.
 168          */
 169         CONNECTION_QUERY,
 170
 171         /*
 172          * CONNECTION_FETCH:
 173          * Execute the 'FETCH' command in the server. The message body shall
 174          * include the hostname of the host to be retrieved.
 175          */
 176         CONNECTION_FETCH,
 177
 178         /*
 179          * CONNECTION_LIST:
 180          * Execute the 'LIST' command in the server. The message body may include
 181          * the type of the objects to be included in addition to all hosts,
 182          * encoded as a 32bit integer in network byte-order.
 183          */
 184         CONNECTION_LIST,
 185
 186         /*
 187          * CONNECTION_LOOKUP:
 188          * Execute the 'LOOKUP' command in the server. The message body shall
 189          * include the conditional expression of the 'MATCHING' clause.
 190          */
 191         CONNECTION_LOOKUP,
 192
 193         /*
 194          * CONNECTION_TIMESERIES:
 195          * Execute the 'TIMESERIES' command in the server. This command is not yet
 196          * supported on the wire. Use CONNECTION_QUERY instead.
 197          */
 198         CONNECTION_TIMESERIES,
 199
 200         /*
 201          * Command subcomponents.
 202          */
 203
 204         /*
 205          * CONNECTION_EXPR:
 206          * A parsed expression. Only used internally.
 207          */
 208         CONNECTION_EXPR = 100,
 209 } sdb_conn_state_t;
 210
 211 #ifdef __cplusplus
 212 } /* extern "C" */
 213 #endif
 214
 215 #endif /* ! SDB_FRONTEND_PROTO_H */
 216
 217 /* vim: set tw=78 sw=4 ts=4 noexpandtab : */
 218