• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 /*
2  * Copyright (c) 2006 Niels Provos <provos@citi.umich.edu>
3  * All rights reserved.
4  *
5  * Redistribution and use in source and binary forms, with or without
6  * modification, are permitted provided that the following conditions
7  * are met:
8  * 1. Redistributions of source code must retain the above copyright
9  *    notice, this list of conditions and the following disclaimer.
10  * 2. Redistributions in binary form must reproduce the above copyright
11  *    notice, this list of conditions and the following disclaimer in the
12  *    documentation and/or other materials provided with the distribution.
13  * 3. The name of the author may not be used to endorse or promote products
14  *    derived from this software without specific prior written permission.
15  *
16  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
17  * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
18  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
19  * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
20  * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
21  * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
22  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
23  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
24  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
25  * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
26  */
27 #ifndef _EVRPC_H_
28 #define _EVRPC_H_
29 
30 #ifdef __cplusplus
31 extern "C" {
32 #endif
33 
34 /** @file evrpc.h
35  *
36  * This header files provides basic support for an RPC server and client.
37  *
38  * To support RPCs in a server, every supported RPC command needs to be
39  * defined and registered.
40  *
41  * EVRPC_HEADER(SendCommand, Request, Reply);
42  *
43  *  SendCommand is the name of the RPC command.
44  *  Request is the name of a structure generated by event_rpcgen.py.
45  *    It contains all parameters relating to the SendCommand RPC.  The
46  *    server needs to fill in the Reply structure.
47  *  Reply is the name of a structure generated by event_rpcgen.py.  It
48  *    contains the answer to the RPC.
49  *
50  * To register an RPC with an HTTP server, you need to first create an RPC
51  * base with:
52  *
53  *   struct evrpc_base *base = evrpc_init(http);
54  *
55  * A specific RPC can then be registered with
56  *
57  * EVRPC_REGISTER(base, SendCommand, Request, Reply,  FunctionCB, arg);
58  *
59  * when the server receives an appropriately formatted RPC, the user callback
60  * is invokved.   The callback needs to fill in the reply structure.
61  *
62  * void FunctionCB(EVRPC_STRUCT(SendCommand)* rpc, void *arg);
63  *
64  * To send the reply, call EVRPC_REQUEST_DONE(rpc);
65  *
66  * See the regression test for an example.
67  */
68 
69 struct evbuffer;
70 struct event_base;
71 struct evrpc_req_generic;
72 
73 /* Encapsulates a request */
74 struct evrpc {
75 	TAILQ_ENTRY(evrpc) next;
76 
77 	/* the URI at which the request handler lives */
78 	const char* uri;
79 
80 	/* creates a new request structure */
81 	void *(*request_new)(void);
82 
83 	/* frees the request structure */
84 	void (*request_free)(void *);
85 
86 	/* unmarshals the buffer into the proper request structure */
87 	int (*request_unmarshal)(void *, struct evbuffer *);
88 
89 	/* creates a new reply structure */
90 	void *(*reply_new)(void);
91 
92 	/* creates a new reply structure */
93 	void (*reply_free)(void *);
94 
95 	/* verifies that the reply is valid */
96 	int (*reply_complete)(void *);
97 
98 	/* marshals the reply into a buffer */
99 	void (*reply_marshal)(struct evbuffer*, void *);
100 
101 	/* the callback invoked for each received rpc */
102 	void (*cb)(struct evrpc_req_generic *, void *);
103 	void *cb_arg;
104 
105 	/* reference for further configuration */
106 	struct evrpc_base *base;
107 };
108 
109 /** The type of a specific RPC Message
110  *
111  * @param rpcname the name of the RPC message
112  */
113 #define EVRPC_STRUCT(rpcname) struct evrpc_req__##rpcname
114 
115 struct evhttp_request;
116 struct evrpc_status;
117 
118 /* We alias the RPC specific structs to this voided one */
119 struct evrpc_req_generic {
120 	/* the unmarshaled request object */
121 	void *request;
122 
123 	/* the empty reply object that needs to be filled in */
124 	void *reply;
125 
126 	/*
127 	 * the static structure for this rpc; that can be used to
128 	 * automatically unmarshal and marshal the http buffers.
129 	 */
130 	struct evrpc *rpc;
131 
132 	/*
133 	 * the http request structure on which we need to answer.
134 	 */
135 	struct evhttp_request* http_req;
136 
137 	/*
138 	 * callback to reply and finish answering this rpc
139 	 */
140 	void (*done)(struct evrpc_req_generic* rpc);
141 };
142 
143 /** Creates the definitions and prototypes for an RPC
144  *
145  * You need to use EVRPC_HEADER to create structures and function prototypes
146  * needed by the server and client implementation.  The structures have to be
147  * defined in an .rpc file and converted to source code via event_rpcgen.py
148  *
149  * @param rpcname the name of the RPC
150  * @param reqstruct the name of the RPC request structure
151  * @param replystruct the name of the RPC reply structure
152  * @see EVRPC_GENERATE()
153  */
154 #define EVRPC_HEADER(rpcname, reqstruct, rplystruct) \
155 EVRPC_STRUCT(rpcname) {	\
156 	struct reqstruct* request; \
157 	struct rplystruct* reply; \
158 	struct evrpc* rpc; \
159 	struct evhttp_request* http_req; \
160 	void (*done)(struct evrpc_status *, \
161 	    struct evrpc* rpc, void *request, void *reply);	     \
162 };								     \
163 int evrpc_send_request_##rpcname(struct evrpc_pool *, \
164     struct reqstruct *, struct rplystruct *, \
165     void (*)(struct evrpc_status *, \
166 	struct reqstruct *, struct rplystruct *, void *cbarg),	\
167     void *);
168 
169 /** Generates the code for receiving and sending an RPC message
170  *
171  * EVRPC_GENERATE is used to create the code corresponding to sending
172  * and receiving a particular RPC message
173  *
174  * @param rpcname the name of the RPC
175  * @param reqstruct the name of the RPC request structure
176  * @param replystruct the name of the RPC reply structure
177  * @see EVRPC_HEADER()
178  */
179 #define EVRPC_GENERATE(rpcname, reqstruct, rplystruct) \
180 int evrpc_send_request_##rpcname(struct evrpc_pool *pool, \
181     struct reqstruct *request, struct rplystruct *reply, \
182     void (*cb)(struct evrpc_status *, \
183 	struct reqstruct *, struct rplystruct *, void *cbarg),	\
184     void *cbarg) { \
185 	struct evrpc_status status;				    \
186 	struct evrpc_request_wrapper *ctx;			    \
187 	ctx = (struct evrpc_request_wrapper *) \
188 	    malloc(sizeof(struct evrpc_request_wrapper));	    \
189 	if (ctx == NULL)					    \
190 		goto error;					    \
191 	ctx->pool = pool;					    \
192 	ctx->evcon = NULL;					    \
193 	ctx->name = strdup(#rpcname);				    \
194 	if (ctx->name == NULL) {				    \
195 		free(ctx);					    \
196 		goto error;					    \
197 	}							    \
198 	ctx->cb = (void (*)(struct evrpc_status *, \
199 		void *, void *, void *))cb;			    \
200 	ctx->cb_arg = cbarg;					    \
201 	ctx->request = (void *)request;				    \
202 	ctx->reply = (void *)reply;				    \
203 	ctx->request_marshal = (void (*)(struct evbuffer *, void *))reqstruct##_marshal; \
204 	ctx->reply_clear = (void (*)(void *))rplystruct##_clear;    \
205 	ctx->reply_unmarshal = (int (*)(void *, struct evbuffer *))rplystruct##_unmarshal; \
206 	return (evrpc_make_request(ctx));			    \
207 error:								    \
208 	memset(&status, 0, sizeof(status));			    \
209 	status.error = EVRPC_STATUS_ERR_UNSTARTED;		    \
210 	(*(cb))(&status, request, reply, cbarg);		    \
211 	return (-1);						    \
212 }
213 
214 /** Provides access to the HTTP request object underlying an RPC
215  *
216  * Access to the underlying http object; can be used to look at headers or
217  * for getting the remote ip address
218  *
219  * @param rpc_req the rpc request structure provided to the server callback
220  * @return an struct evhttp_request object that can be inspected for
221  * HTTP headers or sender information.
222  */
223 #define EVRPC_REQUEST_HTTP(rpc_req) (rpc_req)->http_req
224 
225 /** Creates the reply to an RPC request
226  *
227  * EVRPC_REQUEST_DONE is used to answer a request; the reply is expected
228  * to have been filled in.  The request and reply pointers become invalid
229  * after this call has finished.
230  *
231  * @param rpc_req the rpc request structure provided to the server callback
232  */
233 #define EVRPC_REQUEST_DONE(rpc_req) do { \
234   struct evrpc_req_generic *_req = (struct evrpc_req_generic *)(rpc_req); \
235   _req->done(_req); \
236 } while (0)
237 
238 
239 /* Takes a request object and fills it in with the right magic */
240 #define EVRPC_REGISTER_OBJECT(rpc, name, request, reply) \
241   do { \
242     (rpc)->uri = strdup(#name); \
243     if ((rpc)->uri == NULL) {			 \
244       fprintf(stderr, "failed to register object\n");	\
245       exit(1);						\
246     } \
247     (rpc)->request_new = (void *(*)(void))request##_new; \
248     (rpc)->request_free = (void (*)(void *))request##_free; \
249     (rpc)->request_unmarshal = (int (*)(void *, struct evbuffer *))request##_unmarshal; \
250     (rpc)->reply_new = (void *(*)(void))reply##_new; \
251     (rpc)->reply_free = (void (*)(void *))reply##_free; \
252     (rpc)->reply_complete = (int (*)(void *))reply##_complete; \
253     (rpc)->reply_marshal = (void (*)(struct evbuffer*, void *))reply##_marshal; \
254   } while (0)
255 
256 struct evrpc_base;
257 struct evhttp;
258 
259 /* functions to start up the rpc system */
260 
261 /** Creates a new rpc base from which RPC requests can be received
262  *
263  * @param server a pointer to an existing HTTP server
264  * @return a newly allocated evrpc_base struct
265  * @see evrpc_free()
266  */
267 struct evrpc_base *evrpc_init(struct evhttp *server);
268 
269 /**
270  * Frees the evrpc base
271  *
272  * For now, you are responsible for making sure that no rpcs are ongoing.
273  *
274  * @param base the evrpc_base object to be freed
275  * @see evrpc_init
276  */
277 void evrpc_free(struct evrpc_base *base);
278 
279 /** register RPCs with the HTTP Server
280  *
281  * registers a new RPC with the HTTP server, each RPC needs to have
282  * a unique name under which it can be identified.
283  *
284  * @param base the evrpc_base structure in which the RPC should be
285  *   registered.
286  * @param name the name of the RPC
287  * @param request the name of the RPC request structure
288  * @param reply the name of the RPC reply structure
289  * @param callback the callback that should be invoked when the RPC
290  * is received.  The callback has the following prototype
291  *   void (*callback)(EVRPC_STRUCT(Message)* rpc, void *arg)
292  * @param cbarg an additional parameter that can be passed to the callback.
293  *   The parameter can be used to carry around state.
294  */
295 #define EVRPC_REGISTER(base, name, request, reply, callback, cbarg) \
296   do { \
297     struct evrpc* rpc = (struct evrpc *)calloc(1, sizeof(struct evrpc)); \
298     EVRPC_REGISTER_OBJECT(rpc, name, request, reply); \
299     evrpc_register_rpc(base, rpc, \
300 	(void (*)(struct evrpc_req_generic*, void *))callback, cbarg);	\
301   } while (0)
302 
303 int evrpc_register_rpc(struct evrpc_base *, struct evrpc *,
304     void (*)(struct evrpc_req_generic*, void *), void *);
305 
306 /**
307  * Unregisters an already registered RPC
308  *
309  * @param base the evrpc_base object from which to unregister an RPC
310  * @param name the name of the rpc to unregister
311  * @return -1 on error or 0 when successful.
312  * @see EVRPC_REGISTER()
313  */
314 #define EVRPC_UNREGISTER(base, name) evrpc_unregister_rpc(base, #name)
315 
316 int evrpc_unregister_rpc(struct evrpc_base *base, const char *name);
317 
318 /*
319  * Client-side RPC support
320  */
321 
322 struct evrpc_pool;
323 struct evhttp_connection;
324 
325 /**
326  * provides information about the completed RPC request.
327  */
328 struct evrpc_status {
329 #define EVRPC_STATUS_ERR_NONE		0
330 #define EVRPC_STATUS_ERR_TIMEOUT	1
331 #define EVRPC_STATUS_ERR_BADPAYLOAD	2
332 #define EVRPC_STATUS_ERR_UNSTARTED	3
333 #define EVRPC_STATUS_ERR_HOOKABORTED	4
334 	int error;
335 
336 	/* for looking at headers or other information */
337 	struct evhttp_request *http_req;
338 };
339 
340 struct evrpc_request_wrapper {
341 	TAILQ_ENTRY(evrpc_request_wrapper) next;
342 
343         /* pool on which this rpc request is being made */
344         struct evrpc_pool *pool;
345 
346         /* connection on which the request is being sent */
347 	struct evhttp_connection *evcon;
348 
349 	/* event for implementing request timeouts */
350 	struct event ev_timeout;
351 
352 	/* the name of the rpc */
353 	char *name;
354 
355 	/* callback */
356 	void (*cb)(struct evrpc_status*, void *request, void *reply, void *arg);
357 	void *cb_arg;
358 
359 	void *request;
360 	void *reply;
361 
362 	/* unmarshals the buffer into the proper request structure */
363 	void (*request_marshal)(struct evbuffer *, void *);
364 
365 	/* removes all stored state in the reply */
366 	void (*reply_clear)(void *);
367 
368 	/* marshals the reply into a buffer */
369 	int (*reply_unmarshal)(void *, struct evbuffer*);
370 };
371 
372 /** launches an RPC and sends it to the server
373  *
374  * EVRPC_MAKE_REQUEST() is used by the client to send an RPC to the server.
375  *
376  * @param name the name of the RPC
377  * @param pool the evrpc_pool that contains the connection objects over which
378  *   the request should be sent.
379  * @param request a pointer to the RPC request structure - it contains the
380  *   data to be sent to the server.
381  * @param reply a pointer to the RPC reply structure.  It is going to be filled
382  *   if the request was answered successfully
383  * @param cb the callback to invoke when the RPC request has been answered
384  * @param cbarg an additional argument to be passed to the client
385  * @return 0 on success, -1 on failure
386  */
387 #define EVRPC_MAKE_REQUEST(name, pool, request, reply, cb, cbarg)	\
388 	evrpc_send_request_##name(pool, request, reply, cb, cbarg)
389 
390 int evrpc_make_request(struct evrpc_request_wrapper *);
391 
392 /** creates an rpc connection pool
393  *
394  * a pool has a number of connections associated with it.
395  * rpc requests are always made via a pool.
396  *
397  * @param base a pointer to an struct event_based object; can be left NULL
398  *   in singled-threaded applications
399  * @return a newly allocated struct evrpc_pool object
400  * @see evrpc_pool_free()
401  */
402 struct evrpc_pool *evrpc_pool_new(struct event_base *base);
403 /** frees an rpc connection pool
404  *
405  * @param pool a pointer to an evrpc_pool allocated via evrpc_pool_new()
406  * @see evrpc_pool_new()
407  */
408 void evrpc_pool_free(struct evrpc_pool *pool);
409 /*
410  * adds a connection over which rpc can be dispatched.  the connection
411  * object must have been newly created.
412  */
413 void evrpc_pool_add_connection(struct evrpc_pool *,
414     struct evhttp_connection *);
415 
416 /**
417  * Sets the timeout in secs after which a request has to complete.  The
418  * RPC is completely aborted if it does not complete by then.  Setting
419  * the timeout to 0 means that it never timeouts and can be used to
420  * implement callback type RPCs.
421  *
422  * Any connection already in the pool will be updated with the new
423  * timeout.  Connections added to the pool after set_timeout has be
424  * called receive the pool timeout only if no timeout has been set
425  * for the connection itself.
426  *
427  * @param pool a pointer to a struct evrpc_pool object
428  * @param timeout_in_secs the number of seconds after which a request should
429  *   timeout and a failure be returned to the callback.
430  */
431 void evrpc_pool_set_timeout(struct evrpc_pool *pool, int timeout_in_secs);
432 
433 /**
434  * Hooks for changing the input and output of RPCs; this can be used to
435  * implement compression, authentication, encryption, ...
436  */
437 
438 enum EVRPC_HOOK_TYPE {
439 	EVRPC_INPUT,		/**< apply the function to an input hook */
440 	EVRPC_OUTPUT		/**< apply the function to an output hook */
441 };
442 
443 #ifndef WIN32
444 /** Deprecated alias for EVRPC_INPUT.  Not available on windows, where it
445  * conflicts with platform headers. */
446 #define INPUT EVRPC_INPUT
447 /** Deprecated alias for EVRPC_OUTPUT.  Not available on windows, where it
448  * conflicts with platform headers. */
449 #define OUTPUT EVRPC_OUTPUT
450 #endif
451 
452 /** adds a processing hook to either an rpc base or rpc pool
453  *
454  * If a hook returns -1, the processing is aborted.
455  *
456  * The add functions return handles that can be used for removing hooks.
457  *
458  * @param vbase a pointer to either struct evrpc_base or struct evrpc_pool
459  * @param hook_type either INPUT or OUTPUT
460  * @param cb the callback to call when the hook is activated
461  * @param cb_arg an additional argument for the callback
462  * @return a handle to the hook so it can be removed later
463  * @see evrpc_remove_hook()
464  */
465 void *evrpc_add_hook(void *vbase,
466     enum EVRPC_HOOK_TYPE hook_type,
467     int (*cb)(struct evhttp_request *, struct evbuffer *, void *),
468     void *cb_arg);
469 
470 /** removes a previously added hook
471  *
472  * @param vbase a pointer to either struct evrpc_base or struct evrpc_pool
473  * @param hook_type either INPUT or OUTPUT
474  * @param handle a handle returned by evrpc_add_hook()
475  * @return 1 on success or 0 on failure
476  * @see evrpc_add_hook()
477  */
478 int evrpc_remove_hook(void *vbase,
479     enum EVRPC_HOOK_TYPE hook_type,
480     void *handle);
481 
482 #ifdef __cplusplus
483 }
484 #endif
485 
486 #endif /* _EVRPC_H_ */
487