third_party/libevent/evrpc.h

   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_ */