[API] - JSONRPC Plugin API proposal

[Damian Meden <dm...@apache.org>]

Hello guys,

As you all know there is a new JSONRPC implementation that is up for review
<https://github.com/apache/trafficserver/pull/7478> which is intended to
land in the 10-Dev branch. As a part of this effort and to use all the
benefits of having such protocol in our ATS, I am proposing to add a Plugin
API support so plugins can easily implement their own RPC endpoints which
would let them to have bidirectional communication with ATS JSONRPC clients
such  as *traffic_ctl* or any other implementation willing to talk JSONRPC
2.0 with ATS.

Current state

Currently If a plugin wants to handle external messages they need to
implement the TS_EVENT_LIFECYCLE_MSG hook. This provides a one way only
message system for plugins, plugins can only receive the message but cannot
respond to them directly.

*Proposal*


The goal of this proposal  is to take advantage of the JSONRPC admin node
implementation and let plugins be able to expose JSONRPC nodes(handlers) to
the exterior and have bidirectional communication with clients. All this
can be found in the online generated docs
<https://brbzull0.github.io/ats_plugin_api/developer-guide/api/functions/TSRPCRegister.en.html>

To achieve this we are proposing to introduce a new set of API:



To be added into apidefs.h.in

// JSONRPC 2.0 related interface.
typedef struct tsapi_rpcproviderhandle *TSRPCProviderHandle;
typedef struct tsapi_yaml *TSYaml;

TSRPCProviderHandle will be mapped internally to:

// RPC registration info, this should show information about the rpc
endpoint provider.

// By default all non plugin handlers are part of the same provider with
the following text: Traffic Server JSONRPC 2.0 API

struct RPCRegistryInfo {
  std::string_view provider;
};

TSYaml (possible TSYamlNode would be a better name) will be mapped to
YAML::Node
internally. Please check Binary compatibility notes at the end of this
email.

JSONRPC callback signatures

// Methods

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

// Notifications, no id needed

typedef void (*TSRPCNotificationCb)(TSYaml params);


JSONRPC Registration


Plugins to perform a registration and validation when they are expected to
handle JSONRPC calls should invoke:

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

provider_name:  a string with the Plugin's description.

yamlcpp_lib_version: a string with the yamlcpp library version. A null
terminated string is expected. Why do we need this? check Binary
compatibility down below.

This function returns a new TSRPCProviderHandle or nullptr if the
yamlcpp_lib_version was not set or the yamlcpp version does not match with
the one used internally in TS. The returned TSRPCProviderHandle  will be
set with the  passed provider's name. The caller should pass the returned
TSRPCProviderHandle object to each subsequent
TSRPCRegisterMethod/Notification call.

------------------------------


Add a new registered method handler to the JSON RPC manager.

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

name: Call name to be exposed by the JSONRPC server.

callback: The function to be registered.

info: TSRPCProviderHandle pointer, this will be used to provide more
context information about this call. This object

This function returns TS_SUCCESS if the handler was successfully
registered, TS_ERROR if the handler is already registered.

------------------------------


Add a new registered notification handler to the JSON RPC manager.

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

info:  TSRPCProviderHandle pointer, this will be used to provide more
description to the RPC description. This object should be the one returned
by the TSRPCRegister API.

name: Call name to be exposed by the JSONRPC server.

callback : The function to be registered.

This function returns TS_SUCCESS if the handler was successfully
registered, TS_ERROR if the handler is already registered.


------------------------------


Function to notify the JSONRPC server that the current handler is done
working.

tsapi TSReturnCode TSRPCHandlerDone(TSYaml resp);

This function must be used only when implementing a method JSONRPC 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
<https://brbzull0.github.io/ats/developer-guide/jsonrpc/jsonrpc-architecture.en.html#result>
message will be added to the client's response.

This function  returns TS_SUCCESS if there are no issues. TS_ERROR
otherwise.


------------------------------


Function to notify the JSONRPC server that the current handler is done
working and an error has arisen.

tsapi TSReturnCode TSRPCHandlerError(int code, const char *descr);

This should not be used if you registered your handler as a notification:
TSRPCNotificationCb call.

code: Error code.

descr: A text with a description of the error.

This function  returns TS_SUCCES  if there are no issues. TS_ERROR
otherwise.


------------------------------


Internals

This JSONRPC implementation is based on an iterative server(his own thread)
which handles a single request at a time, this blocks till the response is
handed back to the rpc manager. For plugins this is a bit different as they
need the asynchronous style to deal with some specifics tasks, plugins
needs to be able to run tasks possibly  on different thread and at a
different time that they get called to handle the JSONRPC call, so  to
achieve this the JSONRPC server implements  a notification mechanism(
TSRPCHandlerDone, TSRPCHandlerError) which will let the JSONRPC manager
knows that the plugin handling is complete, either with an error or with a
particular content. Plugins will be able to reschedule the JSONRPC handling
work as they see fit. Examples on how to use this are documented in the
proposal PR.


Binary compatibility with YAMLCPP

Having plugins with different version of YAMLCPP could be an issue, so as
with plugins, we cannot guarantee that a will be compatible across major
versions, so It would be feasible to only provide binary compatibility
within the lifespan of a major release, no new version of YAMLCPP should be
introduced in minor versions.  Eventually plugins will need to
recompile/link

YAMLCPP version check

To help the plugin developers to spot issues, plugins should  check-in
(using TSRPCRegister) with TS before registering any handler and validate
that their yamlcpp version is the same as used internally in TS. Plugins
will inform which version they have and internally we will compare this
against the one used  in ATS (this could be an issue as we can use an
external version of YAMLCPP and not the one shipped with ATS)


You can find some examples here
<https://brbzull0.github.io/ats_plugin_api/developer-guide/jsonrpc/jsonrpc-handler-development.en.html#plugin-api>
.




I have detailed all the new API that is needed in this PR proposal
<https://github.com/brbzull0/trafficserver/pull/4>which is a branch of the
jsonrpc implementation(PR up above)

Best Regards,
Damian.