diff --git a/doc/reference/reference_lua/config.rst b/doc/reference/reference_lua/config.rst index fd6ce0753..6039e9c0c 100644 --- a/doc/reference/reference_lua/config.rst +++ b/doc/reference/reference_lua/config.rst @@ -523,3 +523,9 @@ The ``config.storage`` API allows you to interact with a Tarantool-based :ref:`c :dedent: Example on GitHub: `tarantool_config_storage `_ + +.. toctree:: + :maxdepth: 1 + :includehidden: + + config/utils_schema diff --git a/doc/reference/reference_lua/config/utils_schema.rst b/doc/reference/reference_lua/config/utils_schema.rst new file mode 100644 index 000000000..1c858590b --- /dev/null +++ b/doc/reference/reference_lua/config/utils_schema.rst @@ -0,0 +1,672 @@ +.. _config_utils_schema_module: + +Submodule experimental.config.utils.schema +========================================== + +**Since:** :doc:`3.2.0 ` + +Tarantool allows you to provide arbitrary configurations for cluster applications: + +- For applications loaded using the :ref:`app ` option, :ref:`app.cfg ` is used to provide a configuration. +- For :ref:`custom roles ` developed as a part of a cluster application, :ref:`roles_cfg ` is used. + +The ``experimental.config.utils.schema`` module provides the ability to validate such configurations and process their data: get and set configuration values, filter and transform configuration data, and so on. + +.. important:: + + ``experimental.config.utils.schema`` is an experimental submodule and is subject to changes. + + + + +.. _config_utils_schema_getting_started: + +Getting started with config.utils.schema +---------------------------------------- + +Example config - scalar type: + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/application_validate_cfg_scalar/config.yaml + :language: yaml + :start-at: roles + :dedent: + +1. Load the module: + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/application_validate_cfg_scalar/http_api.lua + :language: lua + :start-at: config.utils.schema + :end-at: config.utils.schema + :dedent: + +2. Define a schema using :ref:`config.utils.schema.new() `. + Example enum: + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/application_validate_cfg_scalar/http_api.lua + :language: lua + :start-at: local http_api_schema + :end-before: local function validate + :dedent: + +3. Validate config values using ``config.utils.schema.validate()``. + For a role, inside the ``validate()`` func: + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/application_validate_cfg_scalar/http_api.lua + :language: lua + :start-at: local function validate + :end-before: local function apply + :dedent: + +4. Get value. For a role, inside the ``apply()`` func: + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/application_validate_cfg_scalar/http_api.lua + :language: lua + :start-at: local function apply + :end-before: local function stop + :dedent: + + + +.. _config_utils_schema_definition: + +Schema definition +----------------- + +Create using :ref:`config.utils.schema.new() `. Options: + +- schema name +- schema node: + + - scalar and composite (record, array, map) types + - annotations (type, validate, and so on) + +- (optional) methods + +.. _config_utils_schema_nodes: + +Schema nodes +~~~~~~~~~~~~ + +.. _config_utils_schema_scalar_composite_types: + +Scalar and composite types +************************** + +There are scalar and composite types. + +- :ref:`config.utils.schema.scalar() ` +- :ref:`config.utils.schema.record() ` +- :ref:`config.utils.schema.map() ` +- :ref:`config.utils.schema.array() ` + +Shortcuts: + +- :ref:`config.utils.schema.enum() ` +- :ref:`config.utils.schema.set() ` + +.. _config_utils_schema_type_system_scalar: + +Scalar +^^^^^^ + +:ref:`config.utils.schema.scalar() ` + +Example config - scalar type: + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/application_validate_cfg_scalar/config.yaml + :language: yaml + :start-at: roles + :dedent: + +Schema definition: + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/application_validate_cfg_scalar/http_api.lua + :language: lua + :start-at: local http_api_schema + :end-before: local function validate + :dedent: + +See also: :ref:`config_utils_schema_annotation`. + + + +.. _record: + +Record +^^^^^^ + +Example config: + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/application_validate_cfg_record/config.yaml + :language: yaml + :start-at: roles + :dedent: + +Schema: + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/application_validate_cfg_record/http_api.lua + :language: lua + :start-at: local listen_address_schema + :end-before: local function validate + :dedent: + +.. _array_record: + +Array +^^^^^ + +Also: :ref:`config.utils.schema.set() ` + +Example config: + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/application_validate_cfg_array_record/config.yaml + :language: yaml + :start-at: roles + :dedent: + +Schema: + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/application_validate_cfg_array_record/http-api.lua + :language: lua + :start-at: local listen_address_schema + :end-before: local function validate + :dedent: + +.. _record_map: + +Map +^^^ + +Example config: + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/application_validate_cfg_record_map/config.yaml + :language: yaml + :start-at: roles + :dedent: + +Schema: + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/application_validate_cfg_record_map/http_api.lua + :language: lua + :start-at: local listen_address_schema + :end-before: local function validate + :dedent: + + +.. _config_utils_schema_annotation: + +Annotations +*********** + +- ``type`` (string) +- (optional) ``validate`` (function) +- (optional) ``allowed_values`` (table) +- (optional) ``default`` (any) +- (optional) ``apply_default_if`` (function) +- (optional) custom annotations + +.. _config_utils_schema_type_annotation: + +Type annotation +^^^^^^^^^^^^^^^ + +The ``type`` annotation. Supported types: + +- ``string`` -- ``string`` +- ``number`` -- ``number`` +- ``integer`` -- ``number`` +- ``boolean`` -- ``boolean`` +- ``any`` - any accepts an arbitrary Lua type, including ``table``. A scalar of the ``any`` type may be used to declare an arbitrary value that doesn't need any validation. +- ``string, number`` -- ``string`` or ``number`` +- ``number, string`` -- ``string`` or ``string`` + + +.. _config_utils_schema_validate_annotation: + +Validate annotation +^^^^^^^^^^^^^^^^^^^ + +Example config: + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/application_validate_cfg_record_annotations/config.yaml + :language: yaml + :start-at: roles + :dedent: + +Schema definition (``validate``, ``allowed_values``, ``default``): + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/application_validate_cfg_record_annotations/http_api.lua + :language: lua + :start-at: local listen_address_schema + :end-before: local function validate + :dedent: + +Validate functions: + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/application_validate_cfg_record_annotations/http_api.lua + :language: lua + :start-at: local function validate_host + :end-before: local listen_address_schema + :dedent: + + + + +.. _config_utils_schema_custom_annotations: + +Custom annotations +^^^^^^^^^^^^^^^^^^ + +``env``: + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/application_validate_cfg_record_fromenv/http_api.lua + :language: lua + :start-at: local listen_address_schema + :end-before: local function collect_env_cfg + :dedent: + +Learn more about getting env vars: :ref:`config_utils_schema_env-vars`. + + +.. _config_utils_schema_computed_annotations: + +Computed annotations +^^^^^^^^^^^^^^^^^^^^ + +Schema node: + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/application_validate_cfg_record_computed_annotations/api.lua + :language: lua + :start-at: local listen_address + :end-before: local http_listen_address_schema + :dedent: + +Valid schema: + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/application_validate_cfg_record_computed_annotations/api.lua + :language: lua + :start-at: local http_listen_address_schema + :end-before: local iproto_listen_address_schema + :dedent: + +Invalid schema: + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/application_validate_cfg_record_computed_annotations/api.lua + :language: lua + :start-at: local iproto_listen_address_schema + :end-before: local function validate + :dedent: + + + +.. _config_utils_schema_methods: + +User-defined methods +~~~~~~~~~~~~~~~~~~~~ + +Example config: + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/application_validate_cfg_record_methods/config.yaml + :language: yaml + :start-at: roles + :dedent: + +Schema: + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/application_validate_cfg_record_methods/http_api.lua + :language: lua + :start-at: local listen_address_schema + :end-before: local function validate + :dedent: + + + + + +.. _config_utils_schema_process_data: + +Processing configuration data +----------------------------- + +.. _config_utils_schema_validating_configuration: + +Validating configuration +~~~~~~~~~~~~~~~~~~~~~~~~ + +TODO + +.. _config_utils_schema_get_configuration: + +Getting configuration values +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +TODO (scalar, record, array, map) + +.. _config_utils_schema_env-vars: + +Parsing environment variables +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +TODO + + +.. _api-reference-config-utils-schema: + +API Reference +------------- + +.. container:: table + + .. rst-class:: left-align-column-1 + .. rst-class:: left-align-column-2 + + .. list-table:: + :widths: 45 55 + + * - **Functions** + - + + * - :ref:`config.utils.schema.array() ` + - TODO + + * - :ref:`config.utils.schema.enum() ` + - TODO + + * - :ref:`config.utils.schema.fromenv() ` + - TODO + + * - :ref:`config.utils.schema.map() ` + - TODO + + * - :ref:`config.utils.schema.new() ` + - TODO + + * - :ref:`config.utils.schema.record() ` + - TODO + + * - :ref:`config.utils.schema.scalar() ` + - TODO + + * - :ref:`config.utils.schema.set() ` + - TODO + + * - **schema_object** + - + + * - :ref:`schema_object:apply_default() ` + - TODO + + * - :ref:`schema_object:filter() ` + - TODO + + * - :ref:`schema_object:get() ` + - TODO + + * - :ref:`schema_object:map() ` + - TODO + + * - :ref:`schema_object.methods ` + - TODO + + * - :ref:`schema_object.name ` + - TODO + + * - :ref:`schema_object:merge() ` + - TODO + + * - :ref:`schema_object:pairs() ` + - TODO + + * - :ref:`schema_object:set() ` + - TODO + + * - :ref:`schema_object.schema ` + - TODO + + * - :ref:`schema_object:validate() ` + - TODO + + * - **schema_node_annotation** + - + + * - :ref:`schema_node_annotation.allowed_values ` + - TODO + + * - :ref:`schema_node_annotation.apply_default_if ` + - TODO + + * - :ref:`schema_node_annotation.default ` + - TODO + + * - :ref:`schema_node_annotation.type ` + - TODO + + * - :ref:`schema_node_annotation.validate ` + - TODO + + * - **schema_node_object** + - + + * - :ref:`schema_node_object.computed.annotations ` + - TODO + + * - :ref:`schema_node_object.fields ` + - TODO + + * - :ref:`schema_node_object.type ` + - TODO + + + + + + + + +.. _config-utils-schema_functions: + +Functions +~~~~~~~~~ + +.. module:: config.utils.schema + +.. _config-utils-schema-array: + +.. function:: schema.array() + + TODO + +.. _config-utils-schema-enum: + +.. function:: schema.enum() + + TODO + +.. _config-utils-schema-fromenv: + +.. function:: schema.fromenv() + + TODO + +.. _config-utils-schema-map: + +.. function:: schema.map() + + TODO + +.. _config-utils-schema-new: + +.. function:: schema.new(schema_name, schema_node[, { methods = <...> }]) + + Create a schema object. + + :param string schema_name: a name + :param table schema_node: a node + :param table methods: methods + + :return: a new schema instance (see :ref:`schema_object `) + :rtype: userdata + + +.. _config-utils-schema-record: + +.. function:: schema.record() + + TODO + +.. _config-utils-schema-scalar: + +.. function:: schema.scalar() + + TODO + +.. _config-utils-schema-set: + +.. function:: schema.set() + + TODO + +---- + + +.. _config-utils-schema_object: + +schema_object +~~~~~~~~~~~~~ + +.. class:: schema_object + + .. _config-schema_object-apply_default: + + .. method:: apply_default(data) + + Apply default values. + + :param any data: data + + :return: new data + + .. _config-schema_object-filter: + + .. method:: filter() + + TODO + + .. _config-schema_object-get: + + .. method:: get() + + TODO + + .. _config-schema_object-map: + + .. method:: map() + + TODO + + .. _config-schema_object-methods: + + .. method:: methods() + + TODO + + .. _config-schema_object-name: + + .. data:: name + + TODO + + .. _config-schema_object-merge: + + .. method:: merge() + + TODO + + .. _config-schema_object-pairs: + + .. method:: pairs() + + TODO + + .. _config-schema_object-set: + + .. method:: set() + + TODO + + .. _config-schema_object-schema: + + .. data:: schema + + TODO + + .. _config-schema_object-validate: + + .. method:: validate() + + TODO + + + + + +.. _config-utils-schema_node_annotation: + +schema_node_annotation +~~~~~~~~~~~~~~~~~~~~~~ + +.. _config-schema_node_annotation-allowed_values: + +.. data:: allowed_values + + TODO + +.. _config-schema_node_annotation-apply_default_if: + +.. data:: apply_default_if + + TODO + +.. _config-schema_node_annotation-default: + +.. data:: default + + TODO + +.. _config-schema_node_annotation-type: + +.. data:: type + + TODO + +.. _config-schema_node_annotation-validate: + +.. data:: validate + + TODO + + +.. _config-utils-schema_node_object: + +schema_node_object +~~~~~~~~~~~~~~~~~~ + +.. class:: schema_node_object + + .. _config-schema_node_object-computed-annotations: + + .. data:: computed.annotations + + TODO + + .. _config-schema_node_object-fields: + + .. data:: fields + + TODO + + .. _config-schema_node_object-type: + + .. data:: type + + TODO