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 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 contain
  57          * the result of the command (if any) encoded as a JSON string.
  58          */
  59         CONNECTION_OK = 0,
  60
  61         /*
  62          * CONNECTION_ERROR:
  63          * Indicates that a command has failed. The message body will contain a
  64          * string describing the error.
  65          */
  66         CONNECTION_ERROR,
  67
  68         /*
  69          * CONNECTION_LOG:
  70          * Indicates an asynchronous log message. The message body will contain
  71          * the message string providing informational or warning logs. Log
  72          * messages may be sent to the client any time.
  73          */
  74         CONNECTION_LOG,
  75 } sdb_conn_status_t;
  76
  77 /* accepted commands / state of the connection */
  78 typedef enum {
  79         /*
  80          * CONNECTION_IDLE:
  81          * This is an internal state used for idle connections.
  82          */
  83         CONNECTION_IDLE = 0,
  84
  85         /*
  86          * CONNECTION_PING:
  87          * Check if the current connection is still alive. The server will reply
  88          * with CONNECTION_OK if it was able to handle the command.
  89          */
  90         CONNECTION_PING,
  91
  92         /*
  93          * CONNECTION_STARTUP:
  94          * Setup of a client connection. The message body shall include the
  95          * username of the user contacting the server. The server may then send
  96          * further requests to the client for authentication (not implemented
  97          * yet). Once the setup and authentication was successful, the server
  98          * replies with CONNECTION_OK. No other messages may be sent to the server
  99          * before this. Also, the server does not send any asynchronous messages
 100          * before startup is complete.
 101          */
 102         CONNECTION_STARTUP,
 103
 104         /*
 105          * Querying the server.
 106          */
 107
 108         /*
 109          * CONNECTION_QUERY:
 110          * Execute a query in the server. The message body shall include a single
 111          * query command as a text string. Multiple commands are ignored by the
 112          * server entirely.
 113          */
 114         CONNECTION_QUERY,
 115
 116         /*
 117          * CONNECTION_FETCH:
 118          * Execute the 'FETCH' command in the server. The message body shall
 119          * include the hostname of the host to be retrieved.
 120          */
 121         CONNECTION_FETCH,
 122
 123         /*
 124          * CONNECTION_LIST:
 125          * Execute the 'LIST' command in the server.
 126          */
 127         CONNECTION_LIST,
 128
 129         /*
 130          * CONNECTION_LOOKUP:
 131          * Execute the 'LOOKUP' command in the server. The message body shall
 132          * include the conditional expression of the 'MATCHING' clause.
 133          */
 134         CONNECTION_LOOKUP,
 135
 136         /*
 137          * CONNECTION_TIMESERIES:
 138          * Execute the 'TIMESERIES' command in the server. This command is not yet
 139          * supported on the wire. Use CONNECTION_QUERY instead.
 140          */
 141         CONNECTION_TIMESERIES,
 142
 143         /*
 144          * Command subcomponents.
 145          */
 146
 147         /*
 148          * CONNECTION_EXPR:
 149          * A parsed expression. Only used internally.
 150          */
 151         CONNECTION_EXPR,
 152 } sdb_conn_state_t;
 153
 154 #ifdef __cplusplus
 155 } /* extern "C" */
 156 #endif
 157
 158 #endif /* ! SDB_FRONTEND_PROTO_H */
 159
 160 /* vim: set tw=78 sw=4 ts=4 noexpandtab : */
 161