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.

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

JSONRPC callback signature for method.

typedef void (*TSRPCNotificationCb)(TSYaml params);

JSONRPC callback signature for notification.

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);
void TSRPCHandlerError(int code, const char *descr, size_t descr_len);

Description

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

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.