doc/developer-guide/jsonrpc/traffic_ctl-development.en.rst - trafficserver - Git at Google

 .. Licensed to the Apache Software Foundation (ASF) under one
    or more contributor license agreements.  See the NOTICE file
    distributed with this work for additional information
    regarding copyright ownership.  The ASF licenses this file
    to you under the Apache License, Version 2.0 (the
    "License"); you may not use this file except in compliance
    with the License.  You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing,
    software distributed under the License is distributed on an
    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
    KIND, either express or implied.  See the License for the
    specific language governing permissions and limitations
    under the License.

 .. include:: ../../common.defs

 .. |RPC| replace:: JSONRPC 2.0

 .. _YAML: https://github.com/jbeder/yaml-cpp/wiki/Tutorial

 .. _developer-guide-traffic_ctl-development:

 Traffic Control Development Guide
 *********************************

 Traffic Control interacts with |TS| through the |RPC| endpoint. All interaction is done by following the |RPC| protocol.

 Overall structure
 =================

 .. figure:: ../../uml/images/traffic_ctl-class-diagram.svg


 * The whole point is to separate the command handling from the printing part.
 * Printing should be done by an appropriate Printer implementation, this should support several kinds of printing formats.
 * For now, everything is printing in the standard output, but a particular printer can be implemented in such way that
   the output could be sent to a different destination.
 * JSONRPC requests have a base class that hides some of the basic and common parts, like ``id``, and ``version``. When deriving
   from this class, the only thing that needs to be override is the ``method``


 .. important::

    CtrlCommand will invoke ``_invoked_func`` when executed, this should be set by the derived class

 * The whole design is that the command will execute the ``_invoked_func`` once invoked. This function ptr should be set by the
   appropriated derived class based on the passed parameters. The derived class have the option to override the execute() which
   is a ``virtual`` function and does something else. Check ``RecordCommand`` as an example.


 Command implementation
 ======================

 #. Add the right command to the ``ArgParser`` object inside the ``traffic_ctl.cc``.
 #. If needed, define a new ``Command`` derived class inside the ``CtrlCommands`` file. if it's not an new command level, and it's a subcommand,
    then you should check the existing command to decide where to place it.

       * Implement the member function that will be dealing with the particular command, ie: (config_status())

       * If a new JsonRPC Message needs to be done, then implement it by deriving from ``shared::rpc::ClientRequest`` if a method is needed, or from
         ``shared::rpc::ClientRequestNotification`` if it's a notification.         More info can be found here :ref:`jsonrpc-request` and
         :ref:`jsonrpc_development-design`. This can be done inside the ``RPCRequest.h`` file.


       .. note::

          Make sure you override the ``std::string get_method() const`` member function with the appropriate api method name.


 #. If needed define a new ``Printer`` derived class inside  the ``CtrlPrinter`` file.

    * If pretty printing format will be supported, then make sure you read the ``_format`` member you get from the ``BasePrinter`` class.

 #. If it's a new command level (like config, metric, etc), make sure you update the ``Command`` creation inside the ``traffic_ctl.cc`` file.

 Implementation Example
 ======================

 Let's define a new command for a new specific API with name == ``admin_new_command_1`` with the following json structure:

 .. code-block: json

    {
       "id":"0f0780a5-0758-4f51-a177-752facc7c0eb",
       "jsonrpc":"2.0",
       "method":"admin_new_command_1",
       "params":{
          "named_var_1":"Some value here"
       }
    }


 .. code-block:: bash

    $ traffic_ctl new-command new-subcommand1

 #. Update ``traffic_ctl.cc``. I will ignore the details as they are trivial.

 #. Define a new Request.

    So based on the above json, we can model our request as:

    .. code-block:: cpp

       // RPCRequests.h
       struct NewCommandJsonRPCRequest : shared::rpc::ClientRequest {
          using super = shared::rpc::ClientRequest;
          struct Params {
             std::string named_var_1;
          };
          NewCommandJsonRPCRequest(Params p)
          {
             super::params = p; // This will invoke the built-in conversion mechanism in the yamlcpp library.
          }
          // Important to override this function, as this is the only way that the "method" field will be set.
          std::string
          get_method() const {
             return "admin_new_command_1";
          }
       };

 #. Implement the yamlcpp convert function, Yaml-cpp has a built-in conversion mechanism. You can refer to `YAML`_ for more info.

    .. code-block:: cpp

       // yaml_codecs.h
       template <> struct convert<NewCommandJsonRPCRequest::Params> {
          static Node
          encode(NewCommandJsonRPCRequest::Params const &params)
          {
             Node node;
             node["named_var_1"] = params.named_var_1;
             return node;
          }
       };

 #. Define a new command. For the sake of simplicity I'll only implement it in the ``.h`` files.

    .. code-block:: cpp

       // CtrlCommands.h & CtrlCommands.cc
       struct NewCommand : public CtrlCommand {
          NewCommand(ts::Arguments args): CtrlCommand(args)
          {
             // we are interested in the format.
             auto fmt = parse_format(_arguments);
             if (args.get("new-subcommand1") {
                // we need to create the right printer.
                _printer = std::make_sharec<MyNewSubcommandPrinter>(fmt);
                // we need to set the _invoked_func that will be called when execute() is called.
                _invoked_func = [&]() { handle_new_subcommand1(); };
             }
             // if more subcommands are needed, then add them here.
          }

       private:
          void handle_new_subcommand1() {
             NewCommandJsonRPCRequest req{};
             // fill the req if needed.
             auto response = invoke_rpc(req);
             _printer->write_output(response);
          }
       };

 #. Define a new printer to deal with this command. We will assume that the printing will be different for every subcommand.
    so we will create our own one.


    .. code-block:: cpp

       class MyNewSubcommandPrinter : public BasePrinter
       {
          void write_output(YAML::Node const &result) override {
             // result will contain what's coming back from the server.
          }
       };

    In case that the format type is important, then we should allow it by accepting the format being passed in the constructor.
    And let it set the base one as well.

    .. code-block:: cpp

       MyNewSubcommandPrinter(BasePrinter::Format fmt) : BasePrinter(fmt) {}


    The way you print and the destination of the message is up to the developer's needs, either a terminal or some other place. If the response
    from the server is a complex object, you can always model the response with your own type and use the built-in yamlcpp mechanism
    to decode the ``YAML::Node``.  ``write_output(YAML::Node const &result)`` will only have the result defined in the protocol,
    check :ref:`jsonrpc-result` for more detail. So something like this can be easily achieved:

    .. code-block:: cpp

          void
          GetHostStatusPrinter::write_output(YAML::Node const &result)
          {
             auto response = result.as<NewCommandJsonRPCRResponse>(); // will invoke the yamlcpp decode.
             // you can now deal with the Record object and not with the yaml node.
          }

 Notes
 =====

 There is code that was written in this way by design, ``RecordPrinter`` and ``RecordRequest`` are meant to be use by any command
 that needs to query and print records without any major hassle.


 See also
 ========

 :ref:`admin-jsonrpc-configuration`,
 :ref:`traffic_ctl_jsonrpc`,
 :ref:`jsonrpc_development`,
 :ref:`jsonrpc-node-errors`
	.. Licensed to the Apache Software Foundation (ASF) under one
	or more contributor license agreements. See the NOTICE file
	distributed with this work for additional information
	regarding copyright ownership. The ASF licenses this file
	to you under the Apache License, Version 2.0 (the
	"License"); you may not use this file except in compliance
	with the License. You may obtain a copy of the License at

	http://www.apache.org/licenses/LICENSE-2.0

	Unless required by applicable law or agreed to in writing,
	software distributed under the License is distributed on an
	"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
	KIND, either express or implied. See the License for the
	specific language governing permissions and limitations
	under the License.

	.. include:: ../../common.defs

	.. \|RPC\| replace:: JSONRPC 2.0

	.. _YAML: https://github.com/jbeder/yaml-cpp/wiki/Tutorial

	.. _developer-guide-traffic_ctl-development:

	Traffic Control Development Guide
	*********************************

	Traffic Control interacts with \|TS\| through the \|RPC\| endpoint. All interaction is done by following the \|RPC\| protocol.

	Overall structure
	=================

	.. figure:: ../../uml/images/traffic_ctl-class-diagram.svg


	* The whole point is to separate the command handling from the printing part.
	* Printing should be done by an appropriate Printer implementation, this should support several kinds of printing formats.
	* For now, everything is printing in the standard output, but a particular printer can be implemented in such way that
	the output could be sent to a different destination.
	* JSONRPC requests have a base class that hides some of the basic and common parts, like ``id``, and ``version``. When deriving
	from this class, the only thing that needs to be override is the ``method``


	.. important::

	CtrlCommand will invoke ``_invoked_func`` when executed, this should be set by the derived class

	* The whole design is that the command will execute the ``_invoked_func`` once invoked. This function ptr should be set by the
	appropriated derived class based on the passed parameters. The derived class have the option to override the execute() which
	is a ``virtual`` function and does something else. Check ``RecordCommand`` as an example.


	Command implementation
	======================

	#. Add the right command to the ``ArgParser`` object inside the ``traffic_ctl.cc``.
	#. If needed, define a new ``Command`` derived class inside the ``CtrlCommands`` file. if it's not an new command level, and it's a subcommand,
	then you should check the existing command to decide where to place it.

	* Implement the member function that will be dealing with the particular command, ie: (config_status())

	* If a new JsonRPC Message needs to be done, then implement it by deriving from ``shared::rpc::ClientRequest`` if a method is needed, or from
	``shared::rpc::ClientRequestNotification`` if it's a notification. More info can be found here :ref:`jsonrpc-request` and
	:ref:`jsonrpc_development-design`. This can be done inside the ``RPCRequest.h`` file.


	.. note::

	Make sure you override the ``std::string get_method() const`` member function with the appropriate api method name.


	#. If needed define a new ``Printer`` derived class inside the ``CtrlPrinter`` file.

	* If pretty printing format will be supported, then make sure you read the ``_format`` member you get from the ``BasePrinter`` class.

	#. If it's a new command level (like config, metric, etc), make sure you update the ``Command`` creation inside the ``traffic_ctl.cc`` file.

	Implementation Example
	======================

	Let's define a new command for a new specific API with name == ``admin_new_command_1`` with the following json structure:

	.. code-block: json

	{
	"id":"0f0780a5-0758-4f51-a177-752facc7c0eb",
	"jsonrpc":"2.0",
	"method":"admin_new_command_1",
	"params":{
	"named_var_1":"Some value here"
	}
	}


	.. code-block:: bash

	$ traffic_ctl new-command new-subcommand1

	#. Update ``traffic_ctl.cc``. I will ignore the details as they are trivial.

	#. Define a new Request.

	So based on the above json, we can model our request as:

	.. code-block:: cpp

	// RPCRequests.h
	struct NewCommandJsonRPCRequest : shared::rpc::ClientRequest {
	using super = shared::rpc::ClientRequest;
	struct Params {
	std::string named_var_1;
	};
	NewCommandJsonRPCRequest(Params p)
	{
	super::params = p; // This will invoke the built-in conversion mechanism in the yamlcpp library.
	}
	// Important to override this function, as this is the only way that the "method" field will be set.
	std::string
	get_method() const {
	return "admin_new_command_1";
	}
	};

	#. Implement the yamlcpp convert function, Yaml-cpp has a built-in conversion mechanism. You can refer to `YAML`_ for more info.

	.. code-block:: cpp

	// yaml_codecs.h
	template <> struct convert<NewCommandJsonRPCRequest::Params> {
	static Node
	encode(NewCommandJsonRPCRequest::Params const &params)
	{
	Node node;
	node["named_var_1"] = params.named_var_1;
	return node;
	}
	};

	#. Define a new command. For the sake of simplicity I'll only implement it in the ``.h`` files.

	.. code-block:: cpp

	// CtrlCommands.h & CtrlCommands.cc
	struct NewCommand : public CtrlCommand {
	NewCommand(ts::Arguments args): CtrlCommand(args)
	{
	// we are interested in the format.
	auto fmt = parse_format(_arguments);
	if (args.get("new-subcommand1") {
	// we need to create the right printer.
	_printer = std::make_sharec<MyNewSubcommandPrinter>(fmt);
	// we need to set the _invoked_func that will be called when execute() is called.
	_invoked_func = [&]() { handle_new_subcommand1(); };
	}
	// if more subcommands are needed, then add them here.
	}

	private:
	void handle_new_subcommand1() {
	NewCommandJsonRPCRequest req{};
	// fill the req if needed.
	auto response = invoke_rpc(req);
	_printer->write_output(response);
	}
	};

	#. Define a new printer to deal with this command. We will assume that the printing will be different for every subcommand.
	so we will create our own one.


	.. code-block:: cpp

	class MyNewSubcommandPrinter : public BasePrinter
	{
	void write_output(YAML::Node const &result) override {
	// result will contain what's coming back from the server.
	}
	};

	In case that the format type is important, then we should allow it by accepting the format being passed in the constructor.
	And let it set the base one as well.

	.. code-block:: cpp

	MyNewSubcommandPrinter(BasePrinter::Format fmt) : BasePrinter(fmt) {}



	The way you print and the destination of the message is up to the developer's needs, either a terminal or some other place. If the response
	from the server is a complex object, you can always model the response with your own type and use the built-in yamlcpp mechanism
	to decode the ``YAML::Node``. ``write_output(YAML::Node const &result)`` will only have the result defined in the protocol,
	check :ref:`jsonrpc-result` for more detail. So something like this can be easily achieved:

	.. code-block:: cpp

	void
	GetHostStatusPrinter::write_output(YAML::Node const &result)
	{
	auto response = result.as<NewCommandJsonRPCRResponse>(); // will invoke the yamlcpp decode.
	// you can now deal with the Record object and not with the yaml node.
	}

	Notes
	=====

	There is code that was written in this way by design, ``RecordPrinter`` and ``RecordRequest`` are meant to be use by any command
	that needs to query and print records without any major hassle.


	See also
	========

	:ref:`admin-jsonrpc-configuration`,
	:ref:`traffic_ctl_jsonrpc`,
	:ref:`jsonrpc_development`,
	:ref:`jsonrpc-node-errors`