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 */
28 #ifndef SDB_FRONTEND_PROTO_H
29 #define SDB_FRONTEND_PROTO_H 1
31 #ifdef __cplusplus
32 extern "C" {
33 #endif
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 */
52 /* status codes returned to a client */
53 typedef enum {
54 /*
55 * Generic status and log messages.
56 */
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,
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,
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,
101 /*
102 * Query-result specific messages.
103 */
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;
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,
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,
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,
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 */
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,
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,
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,
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,
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,
200 /*
201 * Command subcomponents.
202 */
204 /*
205 * CONNECTION_EXPR:
206 * A parsed expression. Only used internally.
207 */
208 CONNECTION_EXPR = 100,
209 } sdb_conn_state_t;
211 #ifdef __cplusplus
212 } /* extern "C" */
213 #endif
215 #endif /* ! SDB_FRONTEND_PROTO_H */
217 /* vim: set tw=78 sw=4 ts=4 noexpandtab : */