TSRPCRegister¶
Traffic Server JSONRPC method registration.
Synopsis¶
#include <ts/ts.h>
-
type TSYaml¶
An opaque pointer to an internal representation of a YAML::Node type from yamlcpp library..
-
type TSRPCProviderHandle¶
An opaque pointer to an internal representation of rpc::RPCRegistryInfo. This object contains context information about the RPC handler.
-
type TSRPCHandlerOptions¶
This class holds information about how a handler will be managed and delivered when called. The JSON-RPC manager would use this object to perform certain validation.
-
bool restricted¶
Tells the RPC Manager if the call can be delivered or not based on the config rules.
-
bool restricted¶
-
typedef void (*TSRPCMethodCb)(const char *id, TSYaml params);¶
JSONRPC callback signature for method.
-
TSRPCProviderHandle TSRPCRegister(const char *provider_name, size_t provider_len, const char *yamlcpp_lib_version, size_t yamlcpp_lib_len);¶
-
TSReturnCode TSRPCRegisterMethodHandler(const char *name, size_t name_len, TSRPCMethodCb callback, TSRPCProviderHandle info, const TSRPCHandlerOptions *opt);¶
-
TSReturnCode TSRPCRegisterNotificationHandler(const char *name, size_t name_len, TSRPCNotificationCb callback, TSRPCProviderHandle info, const TSRPCHandlerOptions *opt);¶
-
TSReturnCode TSRPCHandlerDone(TSYaml resp);¶
Description¶
TSRPCRegister
Should be used to accomplish two basic tasks:
- To perform a
yamlcpp
version library validation. To avoid binary compatibility issues with some plugins using a different
yamlcpp
library version, plugins should check-in with TS before registering any handler and validate that theiryamlcpp
version is the same as used internally in TS.
- To perform a
- To create the
TSRPCProviderHandle
that will be used as a context object for each subsequent handler registration. The
provider_name
will be used as a part of the service descriptor API(get_service_descriptor) which is available as part of the RPC api.TSRPCProviderHandle info = TSRPCRegister("FooBar's Plugin!", 16, "0.8.0", 5); ... TSRPCHandlerOptions opt{{true}}; TSRPCRegisterMethodHandler("my_join_string_handler", 22, func, info, &opt);
Then when requesting get_service_descriptor It will then display as follows:
{ "jsonrpc":"2.0", "result":{ "methods":[ { "name":"my_join_string_handler", "type":"method", "provider":"FooBar's plugin!", "schema":{ } } ] }
- To create the
Note
We will provide binary compatibility within the lifespan of a major release.
provider_name should be a string with the Plugin’s descriptor. A null terminated string is expected.
provider_len should be the length of the provider string..
yamlcpp_lib_version should be a string with the yaml-cpp library version the plugin is using. A null terminated string is expected.
yamlcpp_lib_len should be the length of the yamlcpp_lib_len string.
TSRPCRegisterMethodHandler()
Add new registered method handler to the JSON RPC engine.
name call name to be exposed by the RPC Engine, this should match the incoming request. If you register get_stats then the incoming jsonrpc call should have this very same name in the method field. .. {…’method’: ‘get_stats’…}.
name_len The length of the name string.
callback The function to be registered. Check TSRPCMethodCb
.
info TSRPCProviderHandle pointer,
this will be used to provide more context information about this call. It is expected to use the one created by TSRPCRegister
.
opt Pointer to TSRPCHandlerOptions` object. This will be used to store specifics about a particular call, the rpc manager will use this object to perform certain actions. A copy of this object will be stored by the rpc manager.
Please check Handler implementation for examples.
TSRPCRegisterNotificationHandler()
Add new registered method handler to the JSON RPC engine.
name call name to be exposed by the RPC Engine, this should match the incoming request. If you register get_stats then the incoming jsonrpc call should have this very same name in the method field. .. {…’method’: ‘get_stats’…}.
name_len The length of the name string.
callback The function to be registered. Check TSRPCNotificationCb
.
info TSRPCProviderHandle pointer,
this will be used to provide more context information about this call. It is expected to use the one created by TSRPCRegister
.
opt Pointer to TSRPCHandlerOptions` object. This will be used to store specifics about a particular call, the rpc manager will use this object to perform certain actions. A copy of this object will be stored by the rpc manager.
Please check Handler implementation for examples.
TSRPCHandlerDone()
Function to notify the JSONRPC engine that the plugin handler is finished processing the current request.
This function must be used when implementing a ‘method’ rpc handler. Once the work is done and the
response is ready to be sent back to the client, this function should be called.
Is expected to set the YAML node as response. If the response is empty a success message will be
added to the client’s response. The resp holds the YAML::Node response for this call.
Example:
void my_join_string_handler(const char *id, TSYaml p) { // id = "abcd-id" // join string "["abcd", "efgh"] std::string join = join_string(p); YAML::Node resp; resp["join"] = join; TSRPCHandlerDone(reinterpret_cast<TSYaml>(&resp)); }This will generate:
{ "jsonrpc":"2.0", "result":{ "join":"abcdefgh" }, "id":"abcd-id" }
TSRPCHandlerError()
Function to notify the JSONRPC engine that the plugin handler is finished processing the current request with an error.
code Should be the error number for this particular error.
descr should be a text with a description of the error. It’s up to the developer to specify their own error codes and description. Error will be part of the data field in the jsonrpc response. See Errors
descr_len` The length of the description string.
Example:
void my_handler_func(const char *id, TSYaml p) { try { // some code } catch (std::exception const &e) { std::string buff; swoc::bwprint(buff, "Error during rpc handling: {}.", e.what()); TSRPCHandlerError(ID_123456, buff.c_str(), buff.size()); return; } }This will generate:
{ "jsonrpc":"2.0", "error":{ "code":9, "message":"Error during execution", "data":[ { "code":123456, "message":"Error during rpc handling: File not found." } ] }, "id":"abcd-id" }
Important
You must always inform the RPC after processing the jsonrpc request. Either by calling TSRPCHandlerDone()
or TSRPCHandlerError()
. Calling either of these functions twice is a serious error. You should call exactly one of these functions.
Return Values¶
TSRPCRegister()
returns TS_SUCCESS
if all is good, TS_ERROR
if the yamlcpp_lib_version
was not set, or the yamlcpp
version does not match with the one used internally in TS.
TSRPCRegisterMethodHandler()
TS_SUCCESS
if the handler was successfully registered, TS_ERROR
if the handler is already registered.
TSRPCRegisterNotificationHandler()
TS_SUCCESS
if the handler was successfully registered, TS_ERROR
if the handler is already registered.
TSRPCHandlerDone()
Returns TS_SUCCESS
if no issues, or TS_ERROR
if an issue was found.
TSRPCHandlerError()
Returns TS_SUCCESS
if no issues, or TS_ERROR
if an issue was found.
See also¶
Please check Handler implementation for more details on how to use this API.