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 * Any strings in the message body may not include a zero byte.
44 *
45 * 1 3 4 6
46 * 0 6 2 8 4
47 * +-------------------------------+-------------------------------+
48 * | message type | message length |
49 * +-------------------------------+-------------------------------+
50 * | message body ...
51 *
52 */
54 /* status codes returned to a client */
55 typedef enum {
56 /*
57 * Generic status and log messages.
58 */
60 /*
61 * SDB_CONNECTION_OK:
62 * Indicates that a command was successful. The message body will usually
63 * be empty but may contain a string providing unformatted information
64 * providing more details.
65 *
66 * 0 32 64
67 * +---------------+---------------+
68 * | OK | len(msg) |
69 * +---------------+---------------+
70 * | optional status message ... |
71 */
72 SDB_CONNECTION_OK = 0,
74 /*
75 * SDB_CONNECTION_ERROR:
76 * Indicates that a command has failed. The message body will contain a
77 * string describing the error.
78 *
79 * 0 32 64
80 * +---------------+---------------+
81 * | ERROR | len(msg) |
82 * +---------------+---------------+
83 * | error message ... |
84 */
85 SDB_CONNECTION_ERROR,
87 /*
88 * SDB_CONNECTION_LOG:
89 * Indicates an asynchronous log message. The message body will contain
90 * the log priority (see utils/error.h) and message. Log messages may be
91 * sent to the client any time.
92 *
93 * 0 32 64
94 * +---------------+---------------+
95 * | LOG | length |
96 * +---------------+---------------+
97 * | log priority | log message |
98 * +---------------+ |
99 * | ... |
100 */
101 SDB_CONNECTION_LOG,
103 /*
104 * Query-result specific messages.
105 */
107 /*
108 * SDB_CONNECTION_DATA:
109 * Indicates that a data query was successful. The message body will
110 * contain the type of the data and the result encoded as a JSON string.
111 * The type is the same as the command code of the respective command (see
112 * below) and is stored as an unsigned 32bit integer in network
113 * byte-order. The result may be empty (but the type is still included) if
114 * the query did not return any result. The type and the result message
115 * are empty on empty commands.
116 *
117 * 0 32 64
118 * +---------------+---------------+
119 * | DATA | length |
120 * +---------------+---------------+
121 * | result type | result ... |
122 * +---------------+ |
123 * | ... |
124 */
125 SDB_CONNECTION_DATA = 100,
126 } sdb_conn_status_t;
128 /* accepted commands / state of the connection */
129 typedef enum {
130 /*
131 * SDB_CONNECTION_IDLE:
132 * This is an internal state used for idle connections.
133 */
134 SDB_CONNECTION_IDLE = 0,
136 /*
137 * SDB_CONNECTION_PING:
138 * Check if the current connection is still alive. The server will reply
139 * with SDB_CONNECTION_OK and an empty message body if it was able to
140 * handle the command.
141 *
142 * 0 32 64
143 * +---------------+---------------+
144 * | PING | 0 |
145 * +---------------+---------------+
146 */
147 SDB_CONNECTION_PING,
149 /*
150 * SDB_CONNECTION_STARTUP:
151 * Setup of a client connection. The message body shall include the
152 * username of the user contacting the server. The server may then send
153 * further requests to the client for authentication (not implemented
154 * yet). Once the setup and authentication was successful, the server
155 * replies with SDB_CONNECTION_OK. Further information may be requested
156 * from the server using special messages specific to the authentication
157 * method. The server does not send any asynchronous messages before
158 * startup is complete.
159 *
160 * 0 32 64
161 * +---------------+---------------+
162 * | STARTUP | len(username) |
163 * +---------------+---------------+
164 * | username ... |
165 */
166 SDB_CONNECTION_STARTUP,
168 /*
169 * Querying the server. On success, the server replies with
170 * SDB_CONNECTION_DATA.
171 *
172 * The command codes listed here are used, both, for sending a query to
173 * the server and to indicate the response type from a query in a DATA
174 * message.
175 */
177 /*
178 * SDB_CONNECTION_QUERY:
179 * Execute a query in the server. The message body shall include a single
180 * query command as a text string. Multiple commands are ignored by the
181 * server entirely to protect against injection attacks.
182 *
183 * 0 32 64
184 * +---------------+---------------+
185 * | QUERY | len(query) |
186 * +---------------+---------------+
187 * | query string ... |
188 */
189 SDB_CONNECTION_QUERY,
191 /*
192 * SDB_CONNECTION_FETCH:
193 * Execute the 'FETCH' command in the server. The message body shall
194 * include the type and the identifier of the object to be retrieved.
195 * Hosts are identified by their name. Other types are not supported yet.
196 * The type is encoded as a 32bit integer in network byte-order.
197 *
198 * 0 32 64
199 * +---------------+---------------+
200 * | FETCH | length |
201 * +---------------+---------------+
202 * | object type | identifier |
203 * +---------------+ |
204 * | ... |
205 */
206 SDB_CONNECTION_FETCH,
208 /*
209 * SDB_CONNECTION_LIST:
210 * Execute the 'LIST' command in the server. The message body may include
211 * the type of the objects to be listed, encoded as a 32bit integer in
212 * network byte-order. The response includes all hosts and the respective
213 * child objects. By default, all hosts are listed.
214 *
215 * 0 32 64
216 * +---------------+---------------+
217 * | LIST | length |
218 * +---------------+---------------+
219 * | [object type] |
220 * +---------------+
221 */
222 SDB_CONNECTION_LIST,
224 /*
225 * SDB_CONNECTION_LOOKUP:
226 * Execute the 'LOOKUP' command in the server. The message body shall
227 * include the type of the objects to look up and a string representing
228 * the conditional expression of the 'MATCHING' clause. The type is
229 * encoded as a 32bit integer in network byte-order.
230 *
231 * 0 32 64
232 * +---------------+---------------+
233 * | LOOKUP | length |
234 * +---------------+---------------+
235 * | object type | matching |
236 * +---------------+ |
237 * | clause ... |
238 */
239 SDB_CONNECTION_LOOKUP,
241 /*
242 * SDB_CONNECTION_TIMESERIES:
243 * Execute the 'TIMESERIES' command in the server. This command is not yet
244 * supported on the wire. Use SDB_CONNECTION_QUERY instead.
245 */
246 SDB_CONNECTION_TIMESERIES,
248 /*
249 * SDB_CONNECTION_STORE:
250 * Execute the 'STORE' command in the server. The message body shall
251 * include the type of the object to be stored, the timestamp of the last
252 * update, and a list of fields describing the object depending on the
253 * object type. Object types are encoded as 32bit integers in network
254 * byte-order where attribute types are bitwise ORed with the appropriate
255 * parent object type. Timestamps are encoded as 64bit integers in network
256 * byte-order. Fields are null-terminated strings.
257 *
258 * 0 32 64
259 * +---------------+---------------+
260 * | STORE | length |
261 * +---------------+---------------+
262 * | object type | last_update.. |
263 * +---------------+---------------+
264 * | ... | fields |
265 * +---------------+ |
266 * | ... |
267 *
268 * Fields:
269 *
270 * HOST: name
271 * SERVICE: hostname, name
272 * METRIC: hostname, name, [store type, store id]
273 * ATTRIBUTE: [hostname], parent object name, key, <value>
274 *
275 * Values are encoded as their type (32bit integer in network byte-order),
276 * and their content as implemented by sdb_proto_marshal_data.
277 */
278 SDB_CONNECTION_STORE = 50,
280 /* Only used internally: */
281 SDB_CONNECTION_STORE_HOST,
282 SDB_CONNECTION_STORE_SERVICE,
283 SDB_CONNECTION_STORE_METRIC,
284 SDB_CONNECTION_STORE_ATTRIBUTE,
286 /*
287 * Command subcomponents.
288 */
290 /*
291 * SDB_CONNECTION_MATCHER:
292 * A parsed matcher. Only used internally.
293 */
294 SDB_CONNECTION_MATCHER = 100,
296 /*
297 * SDB_CONNECTION_EXPR:
298 * A parsed expression. Only used internally.
299 */
300 SDB_CONNECTION_EXPR,
302 /*
303 * Server status queries.
304 */
306 /*
307 * SDB_CONNECTION_SERVER_VERSION:
308 * Retrieve the server version. The server replies with SDB_CONNECTION_OK
309 * on success and the server version as an unsigned 32-bit integer,
310 * optionally followed by a string describing extra version components.
311 * The integer server version is encoded as 100000 * major + 100 * minor +
312 * patch.
313 *
314 * 0 32 64
315 * +---------------+---------------+
316 * | SERVER_VERSION| 0 |
317 * +---------------+---------------+
318 */
319 SDB_CONNECTION_SERVER_VERSION = 1000,
320 } sdb_conn_state_t;
322 #define SDB_CONN_MSGTYPE_TO_STRING(t) \
323 (((t) == SDB_CONNECTION_IDLE) ? "IDLE" \
324 : ((t) == SDB_CONNECTION_PING) ? "PING" \
325 : ((t) == SDB_CONNECTION_STARTUP) ? "STARTUP" \
326 : ((t) == SDB_CONNECTION_QUERY) ? "QUERY" \
327 : ((t) == SDB_CONNECTION_FETCH) ? "FETCH" \
328 : ((t) == SDB_CONNECTION_LIST) ? "LIST" \
329 : ((t) == SDB_CONNECTION_LOOKUP) ? "LOOKUP" \
330 : ((t) == SDB_CONNECTION_TIMESERIES) ? "TIMESERIES" \
331 : ((t) == SDB_CONNECTION_STORE) ? "STORE" \
332 : "UNKNOWN")
334 #ifdef __cplusplus
335 } /* extern "C" */
336 #endif
338 #endif /* ! SDB_FRONTEND_PROTO_H */
340 /* vim: set tw=78 sw=4 ts=4 noexpandtab : */