1d549a933bad84f739611f0a61882e4e82e44735
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 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 * 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,
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,
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;
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,
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,
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,
104 /*
105 * Querying the server.
106 */
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,
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,
123 /*
124 * CONNECTION_LIST:
125 * Execute the 'LIST' command in the server.
126 */
127 CONNECTION_LIST,
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,
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,
143 /*
144 * Command subcomponents.
145 */
147 /*
148 * CONNECTION_EXPR:
149 * A parsed expression. Only used internally.
150 */
151 CONNECTION_EXPR,
152 } sdb_conn_state_t;
154 #ifdef __cplusplus
155 } /* extern "C" */
156 #endif
158 #endif /* ! SDB_FRONTEND_PROTO_H */
160 /* vim: set tw=78 sw=4 ts=4 noexpandtab : */