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