You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Adds description of the on_event callback to custom application roles (#5232)
* Adds description of the on_event callback to custom application roles
* Added general info about custom roles as an intro to the section'
* Fixes#4666
Copy file name to clipboardExpand all lines: doc/platform/app/app_roles.rst
+35Lines changed: 35 additions & 0 deletions
Original file line number
Diff line number
Diff line change
@@ -64,13 +64,42 @@ Creating a custom role
64
64
Overview
65
65
~~~~~~~~
66
66
67
+
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.
68
+
For example, a logging role can be created to add logging functionality on top of the built-in one.
69
+
70
+
Since version :doc:`3.4.0 </release/3.4.0>`, you can define an ``on_event`` callback for custom roles. The ``on_event`` callback is called
71
+
every time a ``box.status`` system event is broadcasted.
72
+
If multiple custom roles have the ``on_event`` callback defined, these callbacks are called one after another in the order
73
+
defined by roles dependencies.
74
+
75
+
The ``on_event`` callback returns 3 arguments, when it is called:
76
+
77
+
- ``config``, which contains the configuration of the role;
78
+
79
+
- ``key``, which reflects the trigger event and is set to:
80
+
81
+
- ``config.apply`` if the callback was triggered by a configuration update;
82
+
83
+
- ``box.status`` if it was triggered by the ``box.status`` system event.
84
+
- ``value``, which shows and logs the information about the instance status as in the trigger ``box.status`` system event.
85
+
If the callback is triggered by a configuration update, the ``value`` shows the information of the most recent ``box.status`` system event.
86
+
87
+
.. NOTE::
88
+
89
+
- All ``on_event`` callbacks with the ``config.apply`` key are executed as a part of the configuration process.
90
+
Process statuses ``ready`` or ``check_warnings`` are reached only after all such ``on_event`` callbacks are done.
91
+
92
+
- All ``on_event`` callbacks are executed inside of a ``pcall``. If an error is raised for a callback, it is logged
93
+
with the ``error`` level and the series execution continues.
94
+
67
95
Creating a custom role includes the following steps:
68
96
69
97
#. (Optional) Define the role configuration schema.
70
98
#. Define a function that validates a role configuration.
71
99
#. Define a function that applies a validated configuration.
72
100
#. Define a function that stops a role.
73
101
#. (Optional) Define roles from which this custom role depends on.
102
+
#. (Optional) Define the ``on_event`` callback function.
74
103
75
104
As a result, a role module should return an object that has corresponding functions and fields specified:
76
105
@@ -81,6 +110,12 @@ As a result, a role module should return an object that has corresponding functi
0 commit comments