.. 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
.. highlight:: cpp
.. default-domain:: cpp
.. _JSONRPC: https://www.jsonrpc.org/specification
.. _JSON: https://www.json.org/json-en.html
.. |str| replace:: ``string``
.. |arraynum| replace:: ``array[number]``
.. |arraystr| replace:: ``array[string]``
.. |num| replace:: *number*
.. |strnum| replace:: *string|number*
.. |object| replace:: *object*
.. |array| replace:: *array*
.. |optional| replace:: ``optional``
.. |arrayrecord| replace:: ``array[record]``
.. |arrayerror| replace:: ``array[errors]``
.. |RPC| replace:: JSONRPC 2.0
Architecture
************
Protocol
========
The RPC mechanism implements the `JSONRPC`_ protocol. You can refer to this section `jsonrpc-protocol`_ for more information.
Server
======
.. _jsonrpc-architecture-ipc:
IPC
---
The current server implementation runs on an IPC Socket(Unix Domain Socket). This server implements an iterative server style.
The implementation runs on a dedicated ``TSThread`` and as their style express, this performs blocking calls to all the registered handlers.
Configuration for this particular server style can be found in the admin section :ref:`admin-jsonrpc-configuration`.
Using the JSONRPC mechanism
===========================
As a user, currently, :program:`traffic_ctl` exercises this new protocol, please refer to the :ref:`traffic_ctl_jsonrpc` section.
As a developer, please refer to the :ref:`jsonrpc_development` for a more detailed guide.
JSON Parsing
============
Our JSONRPC protocol implementation uses lib yamlcpp for parsing incoming and outgoing requests,
this allows the server to accept either JSON or YAML format messages which then will be parsed by the protocol implementation. This seems handy
for user that want to feed |TS| with existing yaml configuration without the need to translate yaml into json.
.. note::
:program:`traffic_ctl` have an option to read files from disc and push them into |TS| through the RPC server. Files should be a
valid `JSONRPC`_ message. Please check `traffic_ctl rpc` for more details.
In order to programs communicate with |TS| , This one implements a simple RPC mechanism to expose all the registered API handlers.
You can check all current API by:
.. code-block:: bash
traffic_ctl rpc get-api
or by using the ``show_registered_handlers`` API method.
.. _jsonrpc-protocol:
JSONRPC 2.0 Protocol
====================
JSON-RPC is a stateless, light-weight remote procedure call (RPC) protocol. Primarily this specification defines several data structures
and the rules around their processing. It is transport agnostic in that the concepts can be used within the same process, over sockets,
over http, or in many various message passing environments. It uses JSON (RFC 4627) as data format.
Overview
========
.. note::
Although most of the protocol specs are granted, we have implemented some exceptions. All the modifications will be properly documented.
There are a set of mandatory fields that must be included in a `JSONRPC`_ message as well as some optional fields, all this is documented here,
you also can find this information in the `JSONRPC`_ link.
.. _jsonrpc-request:
Requests
--------
Please find the `jsonrpc 2.0 request` schema for reference ( `mgmt/rpc/schema/jsonrpc_request_schema.json` ).
* Mandatory fields.
============ ====== =======================================================================================
Field Type Description
============ ====== =======================================================================================
``jsonrpc`` |str| Protocol version. |TS| follows the version 2.0 so this field should be only ``2.0``
``method`` |str| Method name that is intended to be invoked.
============ ====== =======================================================================================
* Optional parameters:
* ``params``:
A Structured value that holds the parameter values to be used during the invocation of the method. This member
may be omitted. If passed then a parameters for the rpc call must be provided as a Structured value.
Either by-position through an Array or by-name through an Object.
#. ``by-position`` |array|
params must be an ``array``, containing the values in the server expected order.
.. code-block:: json
{
"params": [
"apache", "traffic", "server"
]
}
.. code-block:: json
{
"params": [
1, 2, 3, 4
]
}
.. code-block:: json
{
"params": [{
"name": "Apache"
},{
"name": "Traffic"
},{
"name": "Server"
}]
}
#. ``by-name``: |object|
Params must be an ``object``, with member names that match the server expected parameter names.
The absence of expected names may result in an error being generated by the server. The names must
match exactly, including case, to the method's expected parameters.
.. code-block:: json
{
"params": {
"name": "Apache"
}
}
* ``id``: |str|.
An identifier established by the Client. If present, the request will be treated as a jsonrpc method and a
response should be expected from the server. If it is not present, the server will treat the request as a
notification and the client should not expect any response back from the server.
*Although a |number| can be specified here we will convert this internally to a |str|. The response will be a |str|.*
.. note::
The |RPC| protocol supports batch requests so, multiple independent requests can be send to the server in a single json message. Batch
request are basically an array of the above request, simply enclose them as an array ``[ .. ]``. The response for batch requests will be also
in a form of an array.
.. _jsonrpc-response:
Responses
---------
Although each individual API call will describe the response details and some specific errors, in this section we will describe a high
level protocol response, some defined by the `JSONRPC`_ specs and some by |TS|
Please find the `jsonrpc 2.0 response` schema for reference( `mgmt/rpc/schema/jsonrpc_response_schema.json` ).
The responses have the following structure:
============ ======== ==============================================
Field Type Description
============ ======== ==============================================
``jsonrpc`` |strnum| A Number that indicates the error type that occurred.
``result`` Result of the invoked operation. See `jsonrpc-result`_
``id`` |strnum| It will be the same as the value of the id member in the `jsonrpc-request`_ .
We will not be using `null` if the `id` could not be fetch from the request,
in that case the field will not be set.
``error`` |object| Error object, it will be present in case of an error. See `jsonrpc-error`_
============ ======== ==============================================
Example 1:
Request
.. code-block:: json
{
"jsonrpc": "2.0",
"result": ["hello", 5],
"id": "9"
}
Response
.. code-block:: json
{
"jsonrpc":"2.0",
"error":{
"code":5,
"message":"Missing method field"
},
"id":"9"
}
As the protocol specifies |TS| have their own set of error, in the example above it's clear that the incoming request is missing
the method name, which |TS| sends a clear response error back.
.. _jsonrpc-result:
Result
------
* This member is required and will be present on success.
* This member will not exist if there was an error invoking the method.
* The value of this member is determined by the method invoked on the Server.
In |TS| a RPC method that does not report any error and have nothing to send back to the client will use the following format to
express that the call was successfully handled and the command was executed.
.. _success_response:
Example:
.. code-block:: json
:emphasize-lines: 4
{
"id": "89fc5aea-0740-11eb-82c0-001fc69cc946",
"jsonrpc": "2.0",
"result": "success"
}
``"result": "success"`` will be set.
.. _jsonrpc-error:
Errors
------
The specs define the error fields that the client must expect to be sent back from the Server in case of any error.
=============== ======== ==============================================
Field Type Description
=============== ======== ==============================================
``code`` |num| A Number that indicates the error type that occurred.
``message`` |str| A String providing a short description of the error.
``data`` |object| This is an optional field that contains additional error data. Depending on the API this could contain data.
=============== ======== ==============================================
# data.
This can be used for nested error so |TS| can inform a detailed error.
=============== ======== ==============================================
Field Type Description
=============== ======== ==============================================
``code`` |str| The error code. Integer type.
``message`` |str| The explanatory string for this error.
=============== ======== ==============================================
Examples:
# Fetch a config record response from |TS|
Request:
.. code-block:: json
{
"id":"0f0780a5-0758-4f51-a177-752facc7c0eb",
"jsonrpc":"2.0",
"method":"admin_lookup_records",
"params":[
{
"record_name":"proxy.config.diags.debug.tags",
"rec_types":[
"1",
"16"
]
}
]
}
Response:
.. code-block:: json
{
"jsonrpc":"2.0",
"result":{
"recordList":[
{
"record":{
"record_name":"proxy.config.diags.debug.tags",
"record_type":"3",
"version":"0",
"raw_stat_block":"0",
"order":"423",
"config_meta":{
"access_type":"0",
"update_status":"0",
"update_type":"1",
"checktype":"0",
"source":"3",
"check_expr":"null"
},
"record_class":"1",
"overridable":"false",
"data_type":"STRING",
"current_value":"rpc",
"default_value":"http|dns"
}
}
]
},
"id":"0f0780a5-0758-4f51-a177-752facc7c0eb"
}
# Getting errors from |TS|
Request an invalid record (invalid name)
.. code-block:: json
{
"id":"f212932f-b260-4f01-9648-8332200524cc",
"jsonrpc":"2.0",
"method":"admin_lookup_records",
"params":[
{
"record_name":"invalid.record",
"rec_types":[
"1",
"16"
]
}
]
}
Response:
.. code-block:: json
{
"jsonrpc":"2.0",
"result":{
"errorList":[
{
"code":"2000",
"record_name":"invalid.record"
}
]
},
"id":"f212932f-b260-4f01-9648-8332200524cc"
}
Parse Error from an incomplete request
.. code-block::
{[[ invalid json
.. code-block:: json
{
"jsonrpc":"2.0",
"error":{
"code":-32700,
"message":"Parse error"
}
}
Invalid method invocation.
Request:
.. code-block:: json
{
"id":"f212932f-b260-4f01-9648-8332200524cc",
"jsonrpc":"2.0",
"method":"some_non_existing_method",
"params":{
}
}
Response:
.. code-block::json
{
"error": {
"code": -32601,
"message": "Method not found"
},
"id": "ded7018e-0720-11eb-abe2-001fc69cc946",
"jsonrpc": "2.0"
}
.. information:
According to the |RPC| specs, if you get an error, the ``result`` field will not be set. |TS| will grant this.
Development Guide
=================
* For details on how to implement JSONRPC handler and expose them through the rpc server, please refer to :ref:`jsonrpc_development`.
* If you need to call a new JSONRPC API through :program:`traffic_ctl`, please refer to :ref:`developer-guide-traffic_ctl-development`
* To interact directly with the |RPC| node, please check :ref:`jsonrpc-node`
See also
========
:ref:`admin-jsonrpc-configuration`,
:ref:`jsonrpc-node-errors`,
:ref:`traffic_ctl_jsonrpc`