ceph/src/spdk/include/spdk/jsonrpc.h

   1 /*-
   2  *   BSD LICENSE
   3  *
   4  *   Copyright (c) Intel Corporation.
   5  *   All rights reserved.
   6  *
   7  *   Redistribution and use in source and binary forms, with or without
   8  *   modification, are permitted provided that the following conditions
   9  *   are met:
  10  *
  11  *     * Redistributions of source code must retain the above copyright
  12  *       notice, this list of conditions and the following disclaimer.
  13  *     * Redistributions in binary form must reproduce the above copyright
  14  *       notice, this list of conditions and the following disclaimer in
  15  *       the documentation and/or other materials provided with the
  16  *       distribution.
  17  *     * Neither the name of Intel Corporation nor the names of its
  18  *       contributors may be used to endorse or promote products derived
  19  *       from this software without specific prior written permission.
  20  *
  21  *   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  22  *   "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  23  *   LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  24  *   A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  25  *   OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  26  *   SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  27  *   LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  28  *   DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  29  *   THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  30  *   (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  31  *   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  32  */
  33
  34 /**
  35  * \file
  36  * JSON-RPC 2.0 server implementation
  37  */
  38
  39 #ifndef SPDK_JSONRPC_H_
  40 #define SPDK_JSONRPC_H_
  41
  42 #include "spdk/stdinc.h"
  43
  44 #include "spdk/json.h"
  45
  46 #ifdef __cplusplus
  47 extern "C" {
  48 #endif
  49
  50 /* Defined error codes in JSON-RPC specification 2.0 */
  51 #define SPDK_JSONRPC_ERROR_PARSE_ERROR          -32700
  52 #define SPDK_JSONRPC_ERROR_INVALID_REQUEST      -32600
  53 #define SPDK_JSONRPC_ERROR_METHOD_NOT_FOUND     -32601
  54 #define SPDK_JSONRPC_ERROR_INVALID_PARAMS       -32602
  55 #define SPDK_JSONRPC_ERROR_INTERNAL_ERROR       -32603
  56
  57 /* Custom error codes in SPDK
  58
  59  * Error codes from and including -32768 to -32000 are reserved for
  60  * predefined errors, hence custom error codes must be outside of the range.
  61  */
  62 #define SPDK_JSONRPC_ERROR_INVALID_STATE        -1
  63
  64 struct spdk_jsonrpc_server;
  65 struct spdk_jsonrpc_request;
  66
  67 struct spdk_jsonrpc_client;
  68 struct spdk_jsonrpc_client_request;
  69
  70 struct spdk_jsonrpc_client_response {
  71         struct spdk_json_val *version;
  72         struct spdk_json_val *id;
  73         struct spdk_json_val *result;
  74         struct spdk_json_val *error;
  75 };
  76
  77 /**
  78  * User callback to handle a single JSON-RPC request.
  79  *
  80  * The user should respond by calling one of spdk_jsonrpc_begin_result() or
  81  * spdk_jsonrpc_send_error_response().
  82  *
  83  * \param request JSON-RPC request to handle.
  84  * \param method Function to handle the request.
  85  * \param param Parameters passed to the function 'method'.
  86  */
  87 typedef void (*spdk_jsonrpc_handle_request_fn)(
  88         struct spdk_jsonrpc_request *request,
  89         const struct spdk_json_val *method,
  90         const struct spdk_json_val *params);
  91
  92 struct spdk_jsonrpc_server_conn;
  93
  94 typedef void (*spdk_jsonrpc_conn_closed_fn)(struct spdk_jsonrpc_server_conn *conn, void *arg);
  95
  96 /**
  97  * Function for specific RPC method response parsing handlers.
  98  *
  99  * \param parser_ctx context where analysis are put.
 100  * \param result json values responsed to this method.
 101  *
 102  * \return 0 on success.
 103  *         SPDK_JSON_PARSE_INVALID on failure.
 104  */
 105 typedef int (*spdk_jsonrpc_client_response_parser)(
 106         void *parser_ctx,
 107         const struct spdk_json_val *result);
 108
 109 /**
 110  * Create a JSON-RPC server listening on the required address.
 111  *
 112  * \param domain Socket family.
 113  * \param protocol Protocol.
 114  * \param listen_addr Listening address.
 115  * \param addrlen Length of address.
 116  * \param handle_request User callback to handle a JSON-RPC request.
 117  *
 118  * \return a pointer to the JSON-RPC server.
 119  */
 120 struct spdk_jsonrpc_server *spdk_jsonrpc_server_listen(int domain, int protocol,
 121                 struct sockaddr *listen_addr, socklen_t addrlen, spdk_jsonrpc_handle_request_fn handle_request);
 122
 123 /**
 124  * Poll the requests to the JSON-RPC server.
 125  *
 126  * This function does accept, receive, handle the requests and reply to them.
 127  *
 128  * \param server JSON-RPC server.
 129  *
 130  * \return 0 on success.
 131  */
 132 int spdk_jsonrpc_server_poll(struct spdk_jsonrpc_server *server);
 133
 134 /**
 135  * Shutdown the JSON-RPC server.
 136  *
 137  * \param server JSON-RPC server.
 138  */
 139 void spdk_jsonrpc_server_shutdown(struct spdk_jsonrpc_server *server);
 140
 141 /**
 142  * Return connection associated to \c request
 143  *
 144  * \param request JSON-RPC request
 145  * \return JSON RPC server connection
 146  */
 147 struct spdk_jsonrpc_server_conn *spdk_jsonrpc_get_conn(struct spdk_jsonrpc_request *request);
 148
 149 /**
 150  * Add callback called when connection is closed. Pair of  \c cb and \c ctx must be unique or error is returned.
 151  * Registered callback is called only once and there is no need to call  \c spdk_jsonrpc_conn_del_close_cb
 152  * inside from \c cb.
 153  *
 154  * \note Current implementation allow only one close callback per connection.
 155  *
 156  * \param conn JSON RPC server connection
 157  * \param cb calback function
 158  * \param ctx argument for \c cb
 159  *
 160  * \return 0 on success, or negated errno code:
 161  *  -EEXIST \c cb and \c ctx is already registered
 162  *  -ENOTCONN Callback can't be added because connection is closed.
 163  *  -ENOSPC no more space to register callback.
 164  */
 165 int spdk_jsonrpc_conn_add_close_cb(struct spdk_jsonrpc_server_conn *conn,
 166                                    spdk_jsonrpc_conn_closed_fn cb, void *ctx);
 167
 168 /**
 169  * Remove registered close callback.
 170  *
 171  * \param conn JSON RPC server connection
 172  * \param cb calback function
 173  * \param ctx argument for \c cb
 174  *
 175  * \return 0 on success, or negated errno code:
 176  *  -ENOENT \c cb and \c ctx pair is not registered
 177  */
 178 int spdk_jsonrpc_conn_del_close_cb(struct spdk_jsonrpc_server_conn *conn,
 179                                    spdk_jsonrpc_conn_closed_fn cb, void *ctx);
 180
 181 /**
 182  * Begin building a response to a JSON-RPC request.
 183  *
 184  * If this function returns non-NULL, the user must call spdk_jsonrpc_end_result()
 185  * on the request after writing the desired response object to the spdk_json_write_ctx.
 186  *
 187  * \param request JSON-RPC request to respond to.
 188
 189  * \return JSON write context to write the response object to, or NULL if no
 190  * response is necessary.
 191  */
 192 struct spdk_json_write_ctx *spdk_jsonrpc_begin_result(struct spdk_jsonrpc_request *request);
 193
 194 /**
 195  * Complete and send a JSON-RPC response.
 196  *
 197  * \param request Request to complete the response for.
 198  * \param w JSON write context returned from spdk_jsonrpc_begin_result().
 199  */
 200 void spdk_jsonrpc_end_result(struct spdk_jsonrpc_request *request, struct spdk_json_write_ctx *w);
 201
 202 /**
 203  * Send an error response to a JSON-RPC request.
 204  *
 205  * This is shorthand for spdk_jsonrpc_begin_result() + spdk_jsonrpc_end_result()
 206  * with an error object.
 207  *
 208  * \param request JSON-RPC request to respond to.
 209  * \param error_code Integer error code to return (may be one of the
 210  * SPDK_JSONRPC_ERROR_ errors, or a custom error code).
 211  * \param msg String error message to return.
 212  */
 213 void spdk_jsonrpc_send_error_response(struct spdk_jsonrpc_request *request,
 214                                       int error_code, const char *msg);
 215
 216 /**
 217  * Send an error response to a JSON-RPC request.
 218  *
 219  * This is shorthand for printf() + spdk_jsonrpc_send_error_response().
 220  *
 221  * \param request JSON-RPC request to respond to.
 222  * \param error_code Integer error code to return (may be one of the
 223  * SPDK_JSONRPC_ERROR_ errors, or a custom error code).
 224  * \param fmt Printf-like format string.
 225  */
 226 void spdk_jsonrpc_send_error_response_fmt(struct spdk_jsonrpc_request *request,
 227                 int error_code, const char *fmt, ...) __attribute__((format(printf, 3, 4)));
 228
 229 /**
 230  * Begin building a JSON-RPC request.
 231  *
 232  * If this function returns non-NULL, the user must call spdk_jsonrpc_end_request()
 233  * on the request after writing the desired request object to the spdk_json_write_ctx.
 234  *
 235  * \param request JSON-RPC request.
 236  * \param id ID index for the request. If < 0 skip ID.
 237  * \param method Name of the RPC method. If NULL caller will have to create "method" key.
 238  *
 239  * \return JSON write context or NULL in case of error.
 240  */
 241 struct spdk_json_write_ctx *
 242 spdk_jsonrpc_begin_request(struct spdk_jsonrpc_client_request *request, int32_t id,
 243                            const char *method);
 244
 245 /**
 246  * Complete a JSON-RPC request.
 247  *
 248  * \param request JSON-RPC request.
 249  * \param w JSON write context returned from spdk_jsonrpc_begin_request().
 250  */
 251 void spdk_jsonrpc_end_request(struct spdk_jsonrpc_client_request *request,
 252                               struct spdk_json_write_ctx *w);
 253
 254 /**
 255  * Connect to the specified RPC server.
 256  *
 257  * \param addr RPC socket address.
 258  * \param addr_family Protocol families of address.
 259  *
 260  * \return JSON-RPC client on success, NULL on failure and errno set to indicate
 261  * the cause of the error.
 262  */
 263 struct spdk_jsonrpc_client *spdk_jsonrpc_client_connect(const char *addr, int addr_family);
 264
 265 /**
 266  * Close JSON-RPC connection and free \c client object.
 267  *
 268  * This function is not thread safe and should only be called from one thread at
 269  * a time while no other threads are actively \c client object.
 270  *
 271  * \param client JSON-RPC client.
 272  */
 273 void spdk_jsonrpc_client_close(struct spdk_jsonrpc_client *client);
 274
 275 /**
 276  * Create one JSON-RPC request. Returned request must be passed to
 277  * \c spdk_jsonrpc_client_send_request when done or to \c spdk_jsonrpc_client_free_request
 278  * if discaded.
 279  *
 280  * \return pointer to JSON-RPC request object.
 281  */
 282 struct spdk_jsonrpc_client_request *spdk_jsonrpc_client_create_request(void);
 283
 284 /**
 285  * Free one JSON-RPC request.
 286  *
 287  * \param req pointer to JSON-RPC request object.
 288  */
 289 void spdk_jsonrpc_client_free_request(struct spdk_jsonrpc_client_request *req);
 290
 291 /**
 292  * Send the JSON-RPC request in JSON-RPC client. Library takes ownership of the
 293  * request object and will free it when done.
 294  *
 295  * This function is not thread safe and should only be called from one thread at
 296  * a time while no other threads are actively \c client object.
 297  *
 298  * \param client JSON-RPC client.
 299  * \param req JSON-RPC request.
 300  *
 301  * \return 0 on success or negative error code.
 302  * -ENOSPC - no space left to queue another request. Try again later.
 303  */
 304 int spdk_jsonrpc_client_send_request(struct spdk_jsonrpc_client *client,
 305                                      struct spdk_jsonrpc_client_request *req);
 306
 307 /**
 308  * Poll the JSON-RPC client. When any response is available use
 309  * \c spdk_jsonrpc_client_get_response to retrieve it.
 310  *
 311  * This function is not thread safe and should only be called from one thread at
 312  * a time while no other threads are actively \c client object.
 313  *
 314  * \param client JSON-RPC client.
 315  * \param timeout Time in miliseconds this function will block. -1 block forever, 0 don't block.
 316  *
 317  * \return If no error occurred, this function returns a non-negative number indicating how
 318  * many ready responses can be retrieved. If an error occurred, this function returns one of
 319  * the following negated errno values:
 320  *  -ENOTCONN - not connected yet. Try again later.
 321  *  -EINVAL - response is detected to be invalid. Client connection should be terminated.
 322  *  -ENOSPC - no space to receive another response. User need to retrieve waiting responses.
 323  *  -EIO - connection terminated (or other critical error). Client connection should be terminated.
 324  *  -ENOMEM - out of memory
 325  */
 326 int spdk_jsonrpc_client_poll(struct spdk_jsonrpc_client *client, int timeout);
 327
 328 /**
 329  * Return JSON RPC response object representing next available response from client connection.
 330  * Returned pointer must be freed using \c spdk_jsonrpc_client_free_response
 331  *
 332  * This function is not thread safe and should only be called from one thread at
 333  * a time while no other threads are actively \c client object.
 334  *
 335  * \param client
 336  * \return pointer to JSON RPC response object or NULL if no response available.
 337  */
 338 struct spdk_jsonrpc_client_response *spdk_jsonrpc_client_get_response(struct spdk_jsonrpc_client
 339                 *client);
 340
 341 /**
 342  * Free response object obtained from \c spdk_jsonrpc_client_get_response
 343  *
 344  * \param resp pointer to JSON RPC response object. If NULL no operation is performed.
 345  */
 346 void spdk_jsonrpc_client_free_response(struct spdk_jsonrpc_client_response *resp);
 347
 348
 349 #ifdef __cplusplus
 350 }
 351 #endif
 352
 353 #endif