From 540beecb7ce3432f75370f2c28c84c3c30e7c21a Mon Sep 17 00:00:00 2001 From: "a.ardeev" Date: Fri, 11 Jul 2025 16:11:46 +0300 Subject: [PATCH 1/3] Moves description of the on_event callback to a separate subsection Adds links from role creation steps to all subsections mentioned in the steps (configuration schema, validation function, apply function, etc.); Fixes #5244 --- doc/platform/app/app_roles.rst | 87 ++++++++++++++++++++++------------ 1 file changed, 58 insertions(+), 29 deletions(-) diff --git a/doc/platform/app/app_roles.rst b/doc/platform/app/app_roles.rst index 52bf795c7..ba9644a6a 100644 --- a/doc/platform/app/app_roles.rst +++ b/doc/platform/app/app_roles.rst @@ -67,39 +67,16 @@ Overview A custom application role is an object which implements custom functions or logic adding to Tarantool's built-in roles and roles provided by third-party Lua modules. For example, a logging role can be created to add logging functionality on top of the built-in one. -Since version :doc:`3.4.0 `, you can define an ``on_event`` callback for custom roles. The ``on_event`` callback is called -every time a ``box.status`` system event is broadcasted. -If multiple custom roles have the ``on_event`` callback defined, these callbacks are called one after another in the order -defined by roles dependencies. - -The ``on_event`` callback returns 3 arguments, when it is called: - -- ``config``, which contains the configuration of the role; -- ``key``, which reflects the trigger event and is set to: - - - ``config.apply`` if the callback was triggered by a configuration update; - - - ``box.status`` if it was triggered by the ``box.status`` system event. -- ``value``, which shows and logs the information about the instance status as in the trigger ``box.status`` system event. - If the callback is triggered by a configuration update, the ``value`` shows the information of the most recent ``box.status`` system event. - -.. NOTE:: - - - All ``on_event`` callbacks with the ``config.apply`` key are executed as a part of the configuration process. - Process statuses ``ready`` or ``check_warnings`` are reached only after all such ``on_event`` callbacks are done. - - - All ``on_event`` callbacks are executed inside of a ``pcall``. If an error is raised for a callback, it is logged - with the ``error`` level and the series execution continues. Creating a custom role includes the following steps: -#. (Optional) Define the role configuration schema. -#. Define a function that validates a role configuration. -#. Define a function that applies a validated configuration. -#. Define a function that stops a role. -#. (Optional) Define roles from which this custom role depends on. -#. (Optional) Define the ``on_event`` callback function. +#. (Optional) Define the :ref:`role configuration schema `. +#. Define a function that :ref:`validates a role configuration `. +#. Define a function that :ref:`applies a validated configuration `. +#. Define a function that :ref:`stops a role `. +#. (Optional) Define roles from which this custom role :ref:`depends on `. +#. (Optional) Define the ``on_event`` :ref:`callback function . As a result, a role module should return an object that has corresponding functions and fields specified: @@ -238,7 +215,59 @@ This means that all the dependencies of a role should be defined in the ``roles` You can find the full example here: `application_role_cfg `_. +.. _roles_create_custom_role_on_event_callback: + +On_event callback + +Since version :doc:`3.4.0 `, you can define the ``on_event`` callback for custom roles. The ``on_event`` callback is called +every time a ``box.status`` system event is broadcasted. +If multiple custom roles have the ``on_event`` callback defined, these callbacks are called one after another in the order +defined by roles dependencies. +The ``on_event`` callback returns 3 arguments, when it is called: + +- ``config``, which contains the configuration of the role; + +- ``key``, which reflects the trigger event and is set to: + + - ``config.apply`` if the callback was triggered by a configuration update; + + - ``box.status`` if it was triggered by the ``box.status`` system event. +- ``value``, which shows and logs the information about the instance status as in the trigger ``box.status`` system event. + If the callback is triggered by a configuration update, the ``value`` shows the information of the most recent ``box.status`` system event. + +.. NOTE:: + + - All ``on_event`` callbacks with the ``config.apply`` key are executed as a part of the configuration process. + Process statuses ``ready`` or ``check_warnings`` are reached only after all such ``on_event`` callbacks are done. + + - All ``on_event`` callbacks are executed inside of a ``pcall``. If an error is raised for a callback, it is logged + with the ``error`` level and the series execution continues. + +.. code-block:: lua + + return { + validate = function() end, + apply = function() + _G.foo = 0 + end, + stop = function() + _G.foo = -1 + _G.bar = nil + end, + on_event = function(config, key, value) + assert(_G.foo >= 0) + assert(config == 12345) + if(_G.foo == 0) then + assert(key == 'config.apply') + else + assert(key == 'box.status') + end + _G.is_ro = value.is_ro + _G.foo = _G.foo + 1 + _G.bar = config + end, + } .. _roles_create_custom_role_init: From 46b8f4722046f7b1e956d57691b9b8b868b7b06b Mon Sep 17 00:00:00 2001 From: "a.ardeev" Date: Fri, 11 Jul 2025 16:41:57 +0300 Subject: [PATCH 2/3] Fix syntax --- doc/platform/app/app_roles.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/doc/platform/app/app_roles.rst b/doc/platform/app/app_roles.rst index ba9644a6a..187b58ec2 100644 --- a/doc/platform/app/app_roles.rst +++ b/doc/platform/app/app_roles.rst @@ -107,7 +107,7 @@ You can omit the optional steps and get a simple role as in the example below. stop = function() -- ... -- end, } -You can modify a role, for example, by adding dependencies or specifying the on_event callback. +You can modify a role, for example, by adding dependencies or specifying the ``on_event`` callback. If you modify a role, you need to restart the Tarantool instance with the role in order to apply the changes. .. NOTE:: @@ -218,6 +218,7 @@ You can find the full example here: `application_role_cfg `, you can define the ``on_event`` callback for custom roles. The ``on_event`` callback is called every time a ``box.status`` system event is broadcasted. From f23dc16b5ca47e97cf38ba1421e9759c5dcdf6c5 Mon Sep 17 00:00:00 2001 From: "a.ardeev" Date: Mon, 14 Jul 2025 14:13:19 +0300 Subject: [PATCH 3/3] Fix by comments --- doc/platform/app/app_roles.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/platform/app/app_roles.rst b/doc/platform/app/app_roles.rst index 187b58ec2..e39c39759 100644 --- a/doc/platform/app/app_roles.rst +++ b/doc/platform/app/app_roles.rst @@ -76,7 +76,7 @@ Creating a custom role includes the following steps: #. Define a function that :ref:`applies a validated configuration `. #. Define a function that :ref:`stops a role `. #. (Optional) Define roles from which this custom role :ref:`depends on `. -#. (Optional) Define the ``on_event`` :ref:`callback function . +#. (Optional) Define the ``on_event`` :ref:`callback function `. As a result, a role module should return an object that has corresponding functions and fields specified: