Fix

Author: p7nov

doc/code_snippets/snippets/config/instances.enabled/application_role_cfg/greeter.lua

@@ -1,15 +1,20 @@
 -- greeter.lua --
 local log = require('log').new("greeter")
+local schema = require('experimental.config.utils.schema')
+
+local greeter_schema = schema.new('greeter', schema.record({
+    greeting = schema.scalar({
+        type = 'string',
+        allowed_values = { 'Hi', 'Hello' }
+    })
+}))
 
 local function validate(cfg)
-    if cfg.greeting then
-        assert(type(cfg.greeting) == "string", "'greeting' should be a string")
-        assert(cfg.greeting == "Hi" or cfg.greeting == "Hello", "'greeting' should be 'Hi' or 'Hello'")
-    end
+    greeter_schema:validate(cfg)
 end
 
 local function apply(cfg)
-    log.info("%s from the 'greeter' role!", cfg.greeting)
+    log.info("%s from the 'greeter' role!", greeter_schema:get(cfg, 'greeting'))
 end
 
 local function stop()

doc/platform/app/app_roles.rst

@@ -27,8 +27,6 @@ To learn how to enable and configure roles, see :ref:`configuration_application_
     -   A role of a replica set in regard to sharding. Learn more in :ref:`vshard_config_sharding_roles`.
 
 
-
-
 .. _roles_create_custom_role_config:
 
 Providing a role configuration
@@ -44,10 +42,15 @@ This example shows how to enable and configure the ``greeter`` role, which is im
     :start-at: instance001
     :dedent:
 
-The role's configuration provided in ``roles_cfg`` can be accessed when :ref:`validating <roles_create_custom_role_validate>` and :ref:`applying <roles_create_custom_role_apply>` this configuration.
+The role configuration provided in ``roles_cfg`` can be accessed when :ref:`validating <roles_create_custom_role_validate>` and :ref:`applying <roles_create_custom_role_apply>` this configuration.
 
-Given that a role is a :ref:`Lua module <app_server-modules>`, a role's name is passed to ``require()`` to obtain the module.
-When :ref:`developing an application <admin-instance_config-develop-app>`, you can place a file with a role's code next to a cluster's configuration file.
+Tarantool includes the :ref:`experimental.config.utils.schema <config_utils_schema_module>`
+built-in module that provides an for managing user-defined configurations
+of applications (``app.cfg``) and roles (``roles_cfg``). The examples below show its
+basic usage.
+
+Given that a role is a :ref:`Lua module <app_server-modules>`, a role name is passed to ``require()`` to obtain the module.
+When :ref:`developing an application <admin-instance_config-develop-app>`, you can place a file with the role code next to the cluster configuration file.
 
 
 
@@ -63,12 +66,12 @@ Overview
 
 Creating a custom role includes the following steps:
 
-1.  Define a function that validates a role's configuration.
+1.  Define a function that validates a role configuration.
 2.  Define a function that applies a validated configuration.
 3.  Define a function that stops a role.
 4.  (Optional) Define roles from which this custom role depends on.
 
-As a result, a role's module should return an object that has corresponding functions and fields specified:
+As a result, a role module should return an object that has corresponding functions and fields specified:
 
 ..  code-block:: lua
 
@@ -86,14 +89,12 @@ The examples below show how to do this.
     Code snippets shown in this section are included from the following application: `application_role_cfg <https://github.com/tarantool/doc/tree/latest/doc/code_snippets/snippets/config/instances.enabled/application_role_cfg>`_.
 
 
-
-
 .. _roles_create_custom_role_validate:
 
 Validating a role configuration
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-To validate a role's configuration, you need to define the :ref:`validate([cfg]) <roles_api_reference_validate>` function.
+To validate a role configuration, you need to define the :ref:`validate([cfg]) <roles_api_reference_validate>` function.
 The ``cfg`` argument provides access to the :ref:`role's configuration <roles_create_custom_role_config>` and check its validity.
 
 In the example below, the ``validate()`` function is used to validate the ``greeting`` configuration value:
@@ -107,8 +108,6 @@ In the example below, the ``validate()`` function is used to validate the ``gree
 If the configuration is not valid, ``validate()`` reports an unrecoverable error by throwing an error object.
 
 
-
-
 .. _roles_create_custom_role_apply:
 
 Applying a role configuration
@@ -117,7 +116,7 @@ Applying a role configuration
 To apply the validated configuration, define the :ref:`apply([cfg]) <roles_api_reference_apply>` function.
 As the ``validate()`` function, ``apply()`` provides access to a role's configuration using the ``cfg`` argument.
 
-In the example below, the ``apply()`` function uses the :ref:`log <log-module>` module to write a role's configuration value to the log:
+In the example below, the ``apply()`` function uses the :ref:`log <log-module>` module to write a value from the role configuration to the log:
 
 ..  literalinclude:: /code_snippets/snippets/config/instances.enabled/application_role_cfg/greeter.lua
     :language: lua
@@ -142,7 +141,7 @@ In the example below, the ``stop()`` function uses the :ref:`log <log-module>` m
     :end-before: return
     :dedent:
 
-When you've defined all the role's functions, you need to return an object that has corresponding functions specified:
+When you've defined all the role functions, you need to return an object that has corresponding functions specified:
 
 ..  literalinclude:: /code_snippets/snippets/config/instances.enabled/application_role_cfg/greeter.lua
     :language: lua

doc/reference/configuration/configuration_reference.rst

@@ -46,6 +46,12 @@ In the ``app`` section, you can load the application and provide an application
 
     Example on GitHub: `application <https://github.com/tarantool/doc/tree/latest/doc/code_snippets/snippets/config/instances.enabled/application>`_
 
+    .. tip::
+
+        The :ref:`experimental.config.utils.schema <config_utils_schema_module>`
+        built-in module provides an API for managing user-defined configurations
+        of applications (``app.cfg``) and roles (``roles_cfg``).
+
     |
     | Type: map
     | Default: nil

doc/reference/reference_lua/config/utils_schema.rst

@@ -52,7 +52,7 @@ the role configuration:
         :end-before: local function validate
         :dedent:
 
-3.  Use the :ref:`schema.validate() <config-schema_object-validate>` function to
+3.  Use the :ref:`validate() <config-schema_object-validate>` function to
     validate configuration values against the schema. In case of a role, call this
     function inside the role's :ref:`validate() <roles_create_custom_role_validate>` function:
 
@@ -62,7 +62,7 @@ the role configuration:
         :end-before: local function apply
         :dedent:
 
-4.  Obtain values of configuration options using :ref:`schema.get() <config-schema_object-get>`.
+4.  Obtain values of configuration options using :ref:`get() <config-schema_object-get>`.
     In case of a role, call it inside the role's :ref:`apply() <roles_create_custom_role_apply>` function:
 
     ..  literalinclude:: /code_snippets/snippets/config/instances.enabled/config_schema_nodes_scalar/http_api.lua
@@ -804,7 +804,7 @@ schema_object
 
         :return: configuration data with applied schema defaults
 
-        **See also:** :ref:`config-schema_node_annotation-default`, :ref:`config-schema_node_annotation-apply_default_if`
+        **See also:** :ref:`default <config-schema_node_annotation-default>`, :ref:`apply_default_if <config-schema_node_annotation-apply_default_if>`
 
     ..  _config-schema_object-filter:
 
@@ -905,7 +905,7 @@ schema_object
         :param any f: walkthrough node, described below
         :param any f_ctx: user-provided context for the transformation function
 
-         :return: transformed configuration data
+        :return: transformed configuration data
 
     ..  _config-schema_object-merge:
 
@@ -981,18 +981,19 @@ schema_object
         The method performs the following checks:
 
         -   field type checks: field values are checked against the schema node types
-        -   allowed values: if a node has the :ref:`config-schema_node_annotation-allowed_values`
-            annotations of schema nodes, the corresponding data field is checked
-            against the allowed values list
+        -   allowed values: if a node has the ``allowed_values`` annotations of schema nodes,
+            the corresponding data field is checked against the allowed values list
         -   validation functions: if a validation function is defined for a node
-            (the :ref:`config-schema_node_annotation-validate` annotation), it is
-            executed to check that the provided value is valid.
+            (the ``validate`` annotation), it is executed to check that the provided value is valid.
 
         :param any data: data
 
         **Example:** see :ref:`config_utils_schema_annotation` and
         :ref:`config_utils_schema_validating_configuration`
 
+        **See also:** :ref:`allowed_values <config-schema_node_annotation-allowed_values>`,
+        :ref:`validate <config-schema_node_annotation-validate>`
+
     ..  _config-schema_object-methods:
 
     ..  data:: methods
@@ -1030,15 +1031,16 @@ parsed by the modules as :ref:`built-in annotations <config_utils_schema_built_i
 
     A list of allowed values for a node.
 
-    **See also** :ref:`config-schema_object-validate`
+    **See also:** :ref:`schema_object:validate() <config-schema_object-validate>`
+
 
 ..  _config-schema_node_annotation-apply_default_if:
 
 -   ``apply_default_if``
 
     A boolean function that defines whether to apply the default value specified
     using ``default``. If this function returns ``true`` on a provided configuration data,
-    the node receives the default value upon the :ref:`config-schema_object-apply_default`
+    the node receives the default value upon the :ref:`schema_object.apply_default() <config-schema_object-apply_default>`
     method call.
 
     The function takes two arguments:
@@ -1050,7 +1052,7 @@ parsed by the modules as :ref:`built-in annotations <config_utils_schema_built_i
         -   ``w.path`` -- the path to the schema node
         -   ``w.error()`` -- a function for printing human-readable error messages
 
-    **See also:** :ref:`config-schema_object-apply_default`.
+    **See also:** :ref:`schema_object:apply_default() <config-schema_object-apply_default>`
 
 ..  _config-schema_node_annotation-default:
 
@@ -1060,7 +1062,7 @@ parsed by the modules as :ref:`built-in annotations <config_utils_schema_built_i
 
     **Example:** see :ref:`config_utils_schema_transform_configuration`
 
-    **See also:** :ref:`config-schema_object-apply_default`
+    **See also:** :ref:`schema_object:apply_default() <config-schema_object-apply_default>`
 
 ..  _config-schema_node_annotation-type:
 
@@ -1075,7 +1077,7 @@ parsed by the modules as :ref:`built-in annotations <config_utils_schema_built_i
 -   ``validate``
 
     A boolean function used to validate node data. Node data is valid if this function
-    returns ``true``. The function is called upon the :ref:`config-schema_object-validate`
+    returns ``true``. The function is called upon the :ref:`schema_object:validate() <config-schema_object-validate>`
     function calls.
 
     The function takes two arguments:
@@ -1087,8 +1089,6 @@ parsed by the modules as :ref:`built-in annotations <config_utils_schema_built_i
         -   ``w.path`` -- the path to the schema node
         -   ``w.error()`` -- a function for printing human-readable error messages
 
-    See also :ref:`config-schema_object-validate`
-
     **Example:**
 
     A function that checks that a string a valid IP address:
@@ -1099,6 +1099,8 @@ parsed by the modules as :ref:`built-in annotations <config_utils_schema_built_i
         :end-before: local function validate_port
         :dedent:
 
+    **See also:** :ref:`schema_object:validate() <config-schema_object-validate>`
+
 ..  _config-utils-schema_node_object:
 
 schema_node_object
@@ -1111,14 +1113,14 @@ schema_node_object
     ..  data:: allowed_values
 
         A list of values allowed for the node. The values are taken from the
-        :ref:`config-schema_node_annotation-allowed_values` node annotation.
+        :ref:`allowed_values <config-schema_node_annotation-allowed_values>` node annotation.
 
     ..  _config-schema_node_object-apply_default_if:
 
     ..  data:: apply_default_if
 
         A function to define when to apply the default node value. The value
-        is taken from the :ref:`config-schema_node_annotation-apply_default_if` annotation.
+        is taken from the :ref:`apply_default_if <config-schema_node_annotation-apply_default_if>` annotation.
 
     ..  _config-schema_node_object-computed:
 
@@ -1131,7 +1133,7 @@ schema_node_object
     ..  data:: default
 
         Node's default value. The value
-        is taken from the :ref:`config-schema_node_annotation-default` annotation.
+        is taken from the :ref:`default <config-schema_node_annotation-default>` annotation.
 
     ..  _config-schema_node_object-fields:
 
@@ -1158,4 +1160,4 @@ schema_node_object
     ..  data:: validate
 
         Node value validation function. The value
-        is taken from the :ref:`config-schema_node_annotation-validate` annotation.
+        is taken from the :ref:`validate <config-schema_node_annotation-validate>` annotation.