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