Code

906f906acbea436c5518dd84e798145a84b4d5ac
[sysdb.git] / src / include / frontend / connection.h
1 /*
2  * SysDB - src/include/frontend/connection.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_CONNECTION_H
29 #define SDB_FRONTEND_CONNECTION_H 1
31 #include "frontend/proto.h"
32 #include "core/store.h"
33 #include "utils/llist.h"
34 #include "utils/strbuf.h"
36 #include <inttypes.h>
38 #ifdef __cplusplus
39 extern "C" {
40 #endif
42 /*
43  * sdb_conn_t represents an open connection from a client. It inherits from
44  * sdb_object_t and may safely be cast to a generic object.
45  */
46 typedef struct sdb_conn sdb_conn_t;
48 /*
49  * sdb_conn_node_t represents an interface for the result of parsing a command
50  * string. The first field of an actual implementation of the interface is a
51  * sdb_conn_state_t in order to fascilitate casting to and from the interface
52  * type to the implementation type.
53  */
54 typedef struct {
55         sdb_object_t super;
56         sdb_conn_state_t cmd;
57 } sdb_conn_node_t;
58 #define SDB_CONN_NODE(obj) ((sdb_conn_node_t *)(obj))
60 /*
61  * sdb_connection_enable_logging:
62  * Enable logging of connection-related messages to the current client
63  * connection. After this function has been called all log messages
64  * originating from the thread handling the current client connection will
65  * also be sent to the client.
66  *
67  * Returns:
68  *  - 0 on success
69  *  - a negative value else
70  */
71 int
72 sdb_connection_enable_logging(void);
74 /*
75  * sdb_connection_accpet:
76  * Accept a new connection on the specified file-descriptor 'fd' and return a
77  * newly allocated connection object.
78  *
79  * Returns:
80  *  - 0 on success
81  *  - a negative value else
82  */
83 sdb_conn_t *
84 sdb_connection_accept(int fd);
86 /*
87  * sdb_connection_close:
88  * Close an open connection. Any subsequent reads from the connection will
89  * fail. Use sdb_object_deref to free the memory used by the object.
90  */
91 void
92 sdb_connection_close(sdb_conn_t *conn);
94 /*
95  * sdb_connection_handle:
96  * Read from an open connection until reading would block and handle all
97  * incoming commands.
98  *
99  * Returns:
100  *  - the number of bytes read (0 on EOF)
101  *  - a negative value on error
102  */
103 ssize_t
104 sdb_connection_handle(sdb_conn_t *conn);
106 /*
107  * sdb_connection_send:
108  * Send to an open connection.
109  *
110  * Returns:
111  *  - the number of bytes written
112  *  - a negative value on error
113  */
114 ssize_t
115 sdb_connection_send(sdb_conn_t *conn, uint32_t code,
116                 uint32_t msg_len, const char *msg);
118 /*
119  * sdb_connection_ping:
120  * Send back a backend status indicator to the connected client.
121  *
122  * Returns:
123  *  - 0 on success
124  *  - a negative value else
125  */
126 int
127 sdb_connection_ping(sdb_conn_t *conn);
129 /*
130  * sdb_fe_parse:
131  * Parse the query text specified in 'query' of length 'len' and return a list
132  * of parse trees (for each command) to be executed by sdb_fe_exec. The list
133  * has to be freed by the caller. If 'len' is less than zero, parse the whole
134  * (nul-terminated) string. If specified, errbuf will be used to record parse
135  * errors.
136  *
137  * Returns:
138  *  - an sdb_llist_t object of sdb_conn_node_t on success
139  *  - NULL in case of an error
140  */
141 sdb_llist_t *
142 sdb_fe_parse(const char *query, int len, sdb_strbuf_t *errbuf);
144 /*
145  * sdb_fe_exec:
146  * Execute the command identified by 'node' on the specified connection.
147  *
148  * Returns:
149  *  - 0 on success
150  *  - a negative value else
151  */
152 int
153 sdb_fe_exec(sdb_conn_t *conn, sdb_conn_node_t *node);
155 /*
156  * session handling
157  */
159 /*
160  * sdb_fe_session_start:
161  * Start a new user session on the specified connection.
162  *
163  * Returns:
164  *  - 0 on success
165  *  - a negative value else
166  */
167 int
168 sdb_fe_session_start(sdb_conn_t *conn);
170 /*
171  * store access
172  */
174 /*
175  * sdb_fe_query, sdb_fe_fetch, sdb_fe_list, sdb_fe_lookup:
176  * Handle the SDB_CONNECTION_QUERY, SDB_CONNECTION_FETCH, SDB_CONNECTION_LIST,
177  * and SDB_CONNECTION_LOOKUP commands respectively. It is expected that the
178  * current command has been initialized already.
179  *
180  * Returns:
181  *  - 0 on success
182  *  - a negative value else
183  */
184 int
185 sdb_fe_query(sdb_conn_t *conn);
186 int
187 sdb_fe_fetch(sdb_conn_t *conn);
188 int
189 sdb_fe_list(sdb_conn_t *conn);
190 int
191 sdb_fe_lookup(sdb_conn_t *conn);
193 /*
194  * sdb_fe_exec_fetch:
195  * Execute the 'FETCH' command. Send the named object of the specified type,
196  * serialized as JSON, to the client. If specified, only objects matching the
197  * filter will be included.
198  *
199  * Returns:
200  *  - 0 on success
201  *  - a negative value else
202  */
203 int
204 sdb_fe_exec_fetch(sdb_conn_t *conn, int type,
205                 const char *hostname, const char *name, sdb_store_matcher_t *filter);
207 /*
208  * sdb_fe_exec_list:
209  * Execute the 'LIST' command. Send a complete listing of the store,
210  * serialized as JSON, to the client. The listing includes all hosts and the
211  * specified object type. If specified, only objects matching the filter will
212  * be included.
213  *
214  * Returns:
215  *  - 0 on success
216  *  - a negative value else
217  */
218 int
219 sdb_fe_exec_list(sdb_conn_t *conn, int type, sdb_store_matcher_t *filter);
221 /*
222  * sdb_fe_exec_lookup:
223  * Execute the 'LOOKUP' command. Send a list of objects of the specified type
224  * matching 'm', serialized as JSON, to the client. If specified, only objects
225  * matching the filter will be included.
226  *
227  * Returns:
228  *  - 0 on success
229  *  - a negative value else
230  */
231 int
232 sdb_fe_exec_lookup(sdb_conn_t *conn, int type,
233                 sdb_store_matcher_t *m, sdb_store_matcher_t *filter);
235 /*
236  * sdb_fe_exec_timeseries:
237  * Execute the 'TIMESERIES' command. Send the time-series for the specified
238  * host's metric, serialized as JSON, to the client. See
239  * sdb_store_fetch_timeseries for details.
240  *
241  * Returns:
242  *  - 0 on success
243  *  - a negative value else
244  */
245 int
246 sdb_fe_exec_timeseries(sdb_conn_t *conn,
247                 const char *hostname, const char *metric,
248                 sdb_timeseries_opts_t *opts);
250 #ifdef __cplusplus
251 } /* extern "C" */
252 #endif
254 #endif /* ! SDB_FRONTEND_CONNECTION_H */
256 /* vim: set tw=78 sw=4 ts=4 noexpandtab : */