TSRPCRegister

Traffic Server JSONRPC method registration.

Synopsis

#include <ts/ts.h>

type TSYaml

type TSRPCProviderHandle

typedef void (*TSRPCMethodCb)(const char *id, TSYaml params);

typedef void (*TSRPCNotificationCb)(TSYaml params);

TSRPCProviderHandle TSRPCRegister(const char *provider_name, const char *yamlcpp_lib_version);

TSReturnCode TSRPCRegisterMethodHandler(const char *name, TSRPCMethodCb callback, TSRPCProviderHandle info);

TSReturnCode TSRPCRegisterNotificationHandler(const char *name, TSRPCNotificationCb callback, TSRPCProviderHandle info);

TSReturnCode TSRPCHandlerDone(TSYaml resp);

void TSRPCHandlerError(int code, const char *descr);

Description

TSRPCMethodCb() JSONRPC callback signature for method.

TSRPCNotificationCb() JSONRPC callback signature for notification.

TSRPCRegister() Should be used to accomplish two basic tasks:

1. 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 their yamlcpp version is the same as used internally in TS.

2. 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!", "0.6.3");
   ...
   TSRPCRegisterMethodHandler("my_join_string_handler", &func, info);
   

   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":{ }
             }
         ]
     }
   

yamlcpp_lib_version should be a string with the yaml-cpp library version the plugin is using. A null terminated string is expected.

provider_name should be a string with the Plugin’s descriptor. A null terminated string is expected.

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’…}. 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.

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’…}. 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.

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

Example:

void my_handler_func(const char *id, TSYaml p) {
    try {
        // some code
    } catch (std::exception const &e) {
        std::string buff;
        ts::bwprint(buff, "Error during rpc handling: {}.", e.what());
        TSRPCHandlerError(ID_123456, buff.c_str());
        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 this functions twice is a serious error. You should call exactly one of this 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.