Skip to content

JSON-RPC: Add support for handler to pass information about the specifics when registering. #8865

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
brbzull0 merged 4 commits into from
Jun 21, 2022
Merged

JSON-RPC: Add support for handler to pass information about the specifics when registering. #8865

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
3707b26
This change adds support for passing Handler Options when registering…
brbzull0 May 25, 2022
be7328f
This commit adds documentation to support the JSON-RPC handler regist…
brbzull0 May 25, 2022
dfe3f54
Add late check for peers credentials on client's socket. RPC handler …
brbzull0 May 25, 2022
f532c93
Address review suggestions
brbzull0 Jun 20, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 27 additions & 18 deletions doc/admin-guide/files/jsonrpc.yaml.en.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@

.. 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
Expand Down Expand Up @@ -56,7 +57,7 @@ In order for programs to communicate with |TS|, the server exposes a
will find some of the configurable arguments that can be changed.


.. _admnin-jsonrpc-configuration:
.. _admin-jsonrpc-configuration:

Configuration
=============
Expand All @@ -68,9 +69,9 @@ Configuration
If a non-default configuration is needed, the following describes the configuration
structure.

File `jsonrpc.yaml` is a YAML format. The default configuration is:
File `jsonrpc.yaml` is a YAML format. The default configuration looks like:
Copy link
Copy Markdown
Contributor

@ywkaras ywkaras Jun 3, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So it's like a default imposter?


.. code:: yaml
.. code-block:: yaml

rpc:
enabled: true
Expand All @@ -90,26 +91,34 @@ Field Name Description
IPC Socket (``unix``)
---------------------

===================================== ==========================================
Unix Domain Socket related configuration.

===================================== =========================================================================================
Field Name Description
===================================== ==========================================
``lock_path_name`` Lock path, including the file name.
(changing this may have impacts in
:program:`traffic_ctl`)
``sock_path_name`` Sock path, including the file name. This
will be used as ``sockaddr_un.sun_path``
(changing this may have impacts in :program:`traffic_ctl`)
===================================== =========================================================================================
``lock_path_name`` Lock path, including the file name. (changing this may have impacts in :program:`traffic_ctl`)
``sock_path_name`` Sock path, including the file name. This will be used as ``sockaddr_un.sun_path``. (changing
this may have impacts in :program:`traffic_ctl`)
``backlog`` Check https://man7.org/linux/man-pages/man2/listen.2.html
``max_retry_on_transient_errors`` Number of times the implementation is
allowed to retry when a transient error is
encountered.
``restricted_api`` Used to set rpc unix socket permissions.
If restricted `0700` will be set, otherwise
`0777`. ``true`` by default.
===================================== ==========================================
``max_retry_on_transient_errors`` Number of times the implementation is allowed to retry when a transient error is encountered.
``restricted_api`` This setting specifies whether the jsonrpc node access should be restricted to root processes.
If this is set to ``false``, then on platforms that support passing process credentials, non-root
processes will be allowed to make read-only JSONRPC calls. Any calls that modify server state
(eg. setting a configuration variable) will still be restricted to root processes. If set to ``true``
then only root processes will be allowed to perform any api call.
If restricted, the Unix Domain Socket will be created with `0700` permissions, otherwise `0777`.
``true`` by default.
In case of an unauthorized call is made, a corresponding rpc error will be returned, you can
check :ref:`jsonrpc-node-errors-unauthorized-action` for details about the errors.
===================================== =========================================================================================


.. note::

Currently, there is only 1 communication mechanism supported. Unix Domain Sockets


See also
========

:ref:`traffic_ctl_jsonrpc`
2 changes: 1 addition & 1 deletion doc/appendices/command-line/traffic_ctl_jsonrpc.en.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -604,5 +604,5 @@ See also

:manpage:`records.config(5)`,
:manpage:`storage.config(5)`,
:ref:`admnin-jsonrpc-configuration`,
:ref:`admin-jsonrpc-configuration`,
:ref:`jsonrpc-protocol`
2 changes: 1 addition & 1 deletion doc/developer-guide/jsonrpc/HandlerError.en.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ API Handler error codes
***********************

High level handler error codes, each particular handler can be fit into one of the following categories.
A good approach could be the following. This required coordination among all the errors, just for now, this soluction seems ok.
A good approach could be the following. This required coordination among all the errors, just for now, this solution seems ok.

.. code-block:: cpp

Expand Down
1 change: 1 addition & 0 deletions doc/developer-guide/jsonrpc/index.en.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,7 @@ JSONRPC
jsonrpc-architecture.en
jsonrpc-api.en
jsonrpc-node.en
jsonrpc-node-errors.en
jsonrpc-handler-development.en
jsonrpc-client-api.en
traffic_ctl-development.en
Expand Down
19 changes: 12 additions & 7 deletions doc/developer-guide/jsonrpc/jsonrpc-api.en.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -960,7 +960,7 @@ Request:

Response:

The response will contain the default `success_response` or an :cpp:class:`RPCErrorCode`.
The response will contain the default `success_response` or a proper rpc error, check :ref:`jsonrpc-node-errors` for mode details.


Validation:
Expand Down Expand Up @@ -1070,7 +1070,7 @@ Parameters
Result
~~~~~~

This api will only inform for errors during the metric update. Errors will be tracked down in the :cpp:class:`RPCErrorCode` field.
This api will only inform for errors during the metric update. Errors will be tracked down in the `error` field.

.. note::

Expand All @@ -1095,7 +1095,7 @@ Request:

Response:

The response will contain the default `success_response` or an :cpp:class:`RPCErrorCode`.
The response will contain the default `success_response` or an error. :ref:`jsonrpc-node-errors`.


.. _admin_host_set_status:
Expand Down Expand Up @@ -1164,7 +1164,7 @@ marking this reason as "down" in that case.
Result
~~~~~~

The response will contain the default `success_response` or an :cpp:class:`RPCErrorCode`.
The response will contain the default `success_response` or an error. :ref:`jsonrpc-node-errors`.


Examples
Expand Down Expand Up @@ -1260,7 +1260,7 @@ Parameters
Result
~~~~~~

The response will contain the default `success_response` or an :cpp:class:`RPCErrorCode`.
The response will contain the default `success_response` or an error. :ref:`jsonrpc-node-errors`.


Examples
Expand Down Expand Up @@ -1302,7 +1302,7 @@ Field Type Description
Result
~~~~~~

The response will contain the default `success_response` or an :cpp:class:`RPCErrorCode`.
The response will contain the default `success_response` or an error. :ref:`jsonrpc-node-errors`.

.. note::

Expand Down Expand Up @@ -1380,7 +1380,7 @@ Field Type Description
Result
~~~~~~

The response will contain the default `success_response` or an :cpp:class:`RPCErrorCode`.
The response will contain the default `success_response` or an error. :ref:`jsonrpc-node-errors`.

Examples
~~~~~~~~
Expand Down Expand Up @@ -1781,3 +1781,8 @@ Response:
]
}
}

See also
========

:ref:`jsonrpc-node-errors`
60 changes: 3 additions & 57 deletions doc/developer-guide/jsonrpc/jsonrpc-architecture.en.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -55,7 +55,7 @@ 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:`admnin-jsonrpc-configuration`.
Configuration for this particular server style can be found in the admin section :ref:`admin-jsonrpc-configuration`.


Using the JSONRPC mechanism
Expand Down Expand Up @@ -464,61 +464,6 @@ Response:
}


.. _rpc-error-code:

Internally we have defined an ``enum`` class that keeps track of the errors that the server will inform in most of the cases.
Some of this errors are already defined by the `JSONRPC`_ specs and some (``>=1``) are defined by |TS|.

.. class:: RPCErrorCode

Defines the API error codes that will be used in case of any RPC error.

.. enumerator:: INVALID_REQUEST = -32600
.. enumerator:: METHOD_NOT_FOUND = -32601
.. enumerator:: INVALID_PARAMS = -32602
.. enumerator:: INTERNAL_ERROR = -32603
.. enumerator:: PARSE_ERROR = -32700

`JSONRPC`_ defined errors.

.. enumerator:: InvalidVersion = 1

The passed version is invalid. must be 2.0

.. enumerator:: InvalidVersionType = 2

The passed version field type is invalid. must be a ``string``

.. enumerator:: MissingVersion = 3

Version field is missing from the request. This field is mandatory.

.. enumerator:: InvalidMethodType = 4

The passed method field type is invalid. must be a ``string``

.. enumerator:: MissingMethod = 5

Method field is missing from the request. This field is mandatory.

.. enumerator:: InvalidParamType = 6

The passed parameter field type is not valid.

.. enumerator:: InvalidIdType = 7

The passed id field type is invalid.

.. enumerator:: NullId = 8

The passed if is ``null``

.. enumerator:: ExecutionError = 9

An error occurred during the execution of the RPC call. This error is used as a generic High level error. The details details about
the error, in most cases are specified in the ``data`` field.


.. information:

According to the |RPC| specs, if you get an error, the ``result`` field will not be set. |TS| will grant this.
Expand All @@ -535,5 +480,6 @@ Development Guide
See also
========

:ref:`admnin-jsonrpc-configuration`,
:ref:`admin-jsonrpc-configuration`,
:ref:`jsonrpc-node-errors`,
:ref:`traffic_ctl_jsonrpc`
7 changes: 5 additions & 2 deletions doc/developer-guide/jsonrpc/jsonrpc-handler-development.en.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -186,7 +186,7 @@ We recommend some ways to deal with this:

This can be set in case you would like to let the server to respond with an |RPC| error, ``ExecutionError`` will be used to catch all the
errors that are fired from within the function call, either by setting the proper errata or by throwing an exception.
Please check the `rpc-error-code` and in particular ``ExecutionError = 9``. Also check :ref:`jsonrpc-handler-errors`
Please check the :ref:`jsonrpc-node-errors` and in particular ``ExecutionError = 9``. Also check :ref:`jsonrpc-handler-errors`

.. important::

Expand Down Expand Up @@ -420,7 +420,10 @@ Important Notes
* To interact directly with the |RPC| node, please check :ref:`jsonrpc-node`


:ref:`admnin-jsonrpc-configuration`
See also
========

:ref:`admin-jsonrpc-configuration`
:ref:`jsonrpc-protocol`
:ref:`developer-guide-traffic_ctl-development`

Expand Down
Loading