diff --git a/doc/code_snippets/snippets/centralized_config/instances.enabled/tarantool_config_storage/myapp_client.lua b/doc/code_snippets/snippets/centralized_config/instances.enabled/tarantool_config_storage/myapp_client.lua new file mode 100644 index 0000000000..39f595ba86 --- /dev/null +++ b/doc/code_snippets/snippets/centralized_config/instances.enabled/tarantool_config_storage/myapp_client.lua @@ -0,0 +1,100 @@ +function put_config() + local fio = require('fio') + local cluster_config_handle = fio.open('../../source.yaml') + local cluster_config = cluster_config_handle:read() + + -- Connect to a config.storage and put the config. + local storage_client = config.storage_client:connect({ + '127.0.0.1:4401', + '127.0.0.1:4402', + '127.0.0.1:4403', + }) + local response = storage_client:put('/myapp/config/all', cluster_config) + + -- Put a config to a configured config.storage cluster. + response = config.storage_client:put('/myapp/config/all', cluster_config) + + cluster_config_handle:close() + + return response +end + +function get_config_by_path() + -- Connect to a config.storage and get /myapp/config/all. + local storage_client = config.storage_client:connect({ + '127.0.0.1:4401', + '127.0.0.1:4402', + '127.0.0.1:4403', + }) + local response = storage_client:get('/myapp/config/all') + + -- Get /myapp/config/all from a configured config.storage cluster. + response = config.storage_client:get('/myapp/config/all') + return response +end + +function get_config_by_prefix() + -- Connect to a config.storage and get values with a /myapp/ prefix. + local storage_client = config.storage_client:connect({ + '127.0.0.1:4401', + '127.0.0.1:4402', + '127.0.0.1:4403', + }) + local response = storage_client:get('/myapp/') + + -- Get values prefixed /myapp/ from a configured config.storage cluster. + response = config.storage_client:get('/myapp/') + return response +end + +function make_txn_request() + -- Connect to a config.storage and execute an atomic request. + local storage_client = config.storage_client:connect({ + '127.0.0.1:4401', + '127.0.0.1:4402', + '127.0.0.1:4403', + }) + local response = storage_client:txn({ + predicates = { { 'value', '==', 'v0', '/myapp/config/all' } }, + on_success = { { 'put', '/myapp/config/all', 'v1' } }, + on_failure = { { 'get', '/myapp/config/all' } } + }) + + -- Execute an atomic request on a configured config.storage cluster. + response = config.storage_client:txn({ + predicates = { { 'value', '==', 'v0', '/myapp/config/all' } }, + on_success = { { 'put', '/myapp/config/all', 'v1' } }, + on_failure = { { 'get', '/myapp/config/all' } } + }) + + return response +end + +function delete_config() + -- Connect to a config.storage and delete a key. + local storage_client = config.storage_client:connect({ + '127.0.0.1:4401', + '127.0.0.1:4402', + '127.0.0.1:4403', + }) + local response = storage_client:delete('/myapp/config/all') + + -- Delete a key on a configured config.storage cluster. + response = config.storage_client:delete('/myapp/config/all') + + return response +end + +function delete_all_configs() + -- Connect to a config.storage and delete all keys. + local storage_client = config.storage_client:connect({ + '127.0.0.1:4401', + '127.0.0.1:4402', + '127.0.0.1:4403', + }) + local response = storage_client:delete('/') + + -- Delete all keys from a configured config.storage cluster. + response = config.storage_client:delete('/') + return response +end diff --git a/doc/reference/reference_lua/config.rst b/doc/reference/reference_lua/config.rst index 6039e9c0c7..e7cb584a25 100644 --- a/doc/reference/reference_lua/config.rst +++ b/doc/reference/reference_lua/config.rst @@ -63,19 +63,28 @@ API Reference * - **config.storage API** - - * - :ref:`config.storage.put() ` + * - :ref:`config.storage ` + - Server API for interacting with config.storage clusters + + * - :ref:`config.storage_client ` + - Client API for interacting with config.storage clusters + + * - :ref:`config.storage_client:connect() ` + - Connect to a remote config.storage cluster + + * - :ref:`:put() ` - Put a value by the specified path - * - :ref:`config.storage.get() ` + * - :ref:`:get() ` - Get a value stored by the specified path - * - :ref:`config.storage.delete() ` + * - :ref:`:delete() ` - Delete a value stored by the specified path - * - :ref:`config.storage.info() ` + * - :ref:`:info() ` - Get information about an instance's connection state - * - :ref:`config.storage.txn() ` + * - :ref:`:txn() ` - Make an atomic request @@ -351,178 +360,261 @@ config API config.storage API ~~~~~~~~~~~~~~~~~~ -The ``config.storage`` API allows you to interact with a Tarantool-based :ref:`centralized configuration storage `. + The ``config.storage`` and ``config.storage_client`` API allows you to interact with Tarantool-based :ref:`centralized configuration storage `. + +.. _config_storage_api_reference: + +.. class:: config.storage -.. module:: config.storage + If you :ref:`configure a replicaset as Tarantool-based centralized configuration storage ` by specifying a ``config.storage`` role (see :ref:`configuring roles `) the ``config.storage`` object provides :ref:`config_storage_object` methods to interact with a key-value storage, see Server API examples below. -.. _config_storage_api_reference_put: +.. _config_storage_client_api_reference: -.. function:: put(path, value) +.. class:: config.storage_client - Put a value by the specified path. +The ``config.stoarge_client`` API allows you to connect to a remote replica set :ref:`configured as a Tarantool-based centralized configuration storage ` and interact with it as a key-value storage, see Client API examples below. - :param string path: a path to put the value by - :param string value: a value to put +If a config.storage config source is configured the ``config.storage_client` provides :`config_storage_object` methods to interact with a remote centralized configuration storage. - :return: a table containing the following fields: +.. _config_storage_client_api_reference_connect: - * ``revision``: a revision after performing the operation +.. function:: connect(endpoints[, options]) + + Connect to a remote config.storage cluster. + + :param table endpoints: a path to put the value by + :param table options: extra options + + :return: a object :rtype: table - **Example:** +.. _config_storage_object_api_reference: - The example below shows how to read a configuration stored in the ``source.yaml`` file using the :ref:`fio module ` API and put this configuration by the ``/myapp/config/all`` path: +.. class:: config_storage_object - .. literalinclude:: /code_snippets/snippets/centralized_config/instances.enabled/tarantool_config_storage/myapp.lua - :language: lua - :start-after: function put_config - :end-at: cluster_config_handle:close() - :dedent: + .. _config_storage_object_api_reference_put: - Example on GitHub: `tarantool_config_storage `_ + .. method:: put(path, value) + Put a value by the specified path. -.. _config_storage_api_reference_get: + :param string path: a path to put the value by + :param string value: a value to put -.. function:: get(path) + :return: a table containing the following fields: - Get a value stored by the specified path or prefix. + * ``recvision``: a revision after performing the operation - :param string path: a path or prefix to get a value by; prefixes end with ``/`` + :rtype: table - :return: a table containing the following fields: + **Server API example:** - * ``data``: a table containing the information about the value: + The example below shows how to read a configuration stored in the ``source.yaml`` file using the :ref:`fio module ` API and put this configuration by the ``/myapp/config/all`` path: - * ``path``: a path - * ``mod_revision``: the last revision at which this value was modified - * ``value:``: a value + .. literalinclude:: /code_snippets/snippets/centralized_config/instances.enabled/tarantool_config_storage/myapp.lua + :language: lua + :start-after: function put_config + :end-at: cluster_config_handle:close() + :dedent: - * ``revision``: a revision after performing the operation + **Client API exapmle:** - :rtype: table + The example below shows how to read a configuration stored in the ``source.yaml`` file using the :ref:`fio module ` API and put this configuration by the ``/myapp/config/all`` path: - **Examples:** + .. literalinclude:: /code_snippets/snippets/centralized_config/instances.enabled/tarantool_config_storage/myapp_client.lua + :language: lua + :start-after: function put_config + :end-at: cluster_config_handle:close() + :dedent: - The example below shows how to get a configuration stored by the ``/myapp/config/all`` path: + Examples on GitHub: `tarantool_config_storage `_ - .. literalinclude:: /code_snippets/snippets/centralized_config/instances.enabled/tarantool_config_storage/myapp.lua - :language: lua - :start-after: get_config_by_path - :end-at: get('/myapp/config/all') - :dedent: - This example shows how to get all configurations stored by the ``/myapp/`` prefix: + .. _config_storage_object_api_reference_get: - .. literalinclude:: /code_snippets/snippets/centralized_config/instances.enabled/tarantool_config_storage/myapp.lua - :language: lua - :start-after: get_config_by_prefix - :end-at: get('/myapp/') - :dedent: + .. method:: get(path) - Example on GitHub: `tarantool_config_storage `_ + Get a value stored by the specified path or prefix. -.. _config_storage_api_reference_delete: + :param string path: a path or prefix to get a value by; prefixes end with ``/`` -.. function:: delete(path) + :return: a table containing the following fields: - Delete a value stored by the specified path or prefix. + * ``data``: a table containing the information about the value: - :param string path: a path or prefix to delete the value by; prefixes end with ``/`` + * ``path``: a path + * ``mod_revision``: the last revision at which this value was modified + * ``value:``: a value - :return: a table containing the following fields: + * ``revision``: a revision after performing the operation - * ``data``: a table containing the information about the value: + :rtype: table - * ``path``: a path - * ``mod_revision``: the last revision at which this value was modified - * ``value:``: a value + **Server API examples:** - * ``revision``: a revision after performing the operation + The example below shows how to get a configuration stored by the ``/myapp/config/all`` path: - :rtype: table + .. literalinclude:: /code_snippets/snippets/centralized_config/instances.enabled/tarantool_config_storage/myapp.lua + :language: lua + :start-after: get_config_by_path + :end-at: get('/myapp/config/all') + :dedent: - **Examples:** + This example shows how to get all configurations stored by the ``/myapp/`` prefix: - The example below shows how to delete a configuration stored by the ``/myapp/config/all`` path: + .. literalinclude:: /code_snippets/snippets/centralized_config/instances.enabled/tarantool_config_storage/myapp.lua + :language: lua + :start-after: get_config_by_prefix + :end-at: get('/myapp/') + :dedent: - .. literalinclude:: /code_snippets/snippets/centralized_config/instances.enabled/tarantool_config_storage/myapp.lua - :language: lua - :start-after: delete_config - :end-at: delete('/myapp/config/all') - :dedent: + **Client API examples:** - In this example, all configuration are deleted: + The example below shows how to get a configuration stored by the ``/myapp/config/all`` path on a remote config.storage cluster: - .. literalinclude:: /code_snippets/snippets/centralized_config/instances.enabled/tarantool_config_storage/myapp.lua - :language: lua - :start-after: delete_all_configs - :end-at: delete('/') - :dedent: + .. literalinclude:: /code_snippets/snippets/centralized_config/instances.enabled/tarantool_config_storage/myapp_client.lua + :language: lua + :start-after: get_config_by_path + :end-at: get('/myapp/config/all') + :dedent: - Example on GitHub: `tarantool_config_storage `_ + This example shows how to get all configurations stored by the ``/myapp/`` prefix on a remote config.storage cluster: + .. literalinclude:: /code_snippets/snippets/centralized_config/instances.enabled/tarantool_config_storage/myapp_client.lua + :language: lua + :start-after: get_config_by_prefix + :end-at: get('/myapp/') + :dedent: -.. _config_storage_api_reference_info: + Examples on GitHub: `tarantool_config_storage `_ -.. function:: info() + .. _config_storage_object_api_reference_delete: - Get information about an instance's connection state. + .. method:: delete(path) - :return: a table containing the following fields: + Delete a value stored by the specified path or prefix. - * ``status``: a connection status, which can be one of the following: + :param string path: a path or prefix to delete the value by; prefixes end with ``/`` - * ``connected``: if any instance from the quorum is available to the current instance - * ``disconnected``: if the current instance doesn't have a connection with the quorum + :return: a table containing the following fields: - :rtype: table + * ``data``: a table containing the information about the value: + * ``path``: a path + * ``mod_revision``: the last revision at which this value was modified + * ``value:``: a value -.. _config_storage_api_reference_txn: + * ``revision``: a revision after performing the operation -.. function:: txn(request) + :rtype: table - Make an atomic request. + **Server API examples:** - :param table request: a table containing the following optional fields: + The example below shows how to delete a configuration stored by the ``/myapp/config/all`` path: - * ``predicates``: a list of predicates to check. Each predicate is a list that contains: + .. literalinclude:: /code_snippets/snippets/centralized_config/instances.enabled/tarantool_config_storage/myapp.lua + :language: lua + :start-after: delete_config + :end-at: delete('/myapp/config/all') + :dedent: - .. code-block:: none + In this example, all configuration are deleted: - {target, operator, value[, path]} + .. literalinclude:: /code_snippets/snippets/centralized_config/instances.enabled/tarantool_config_storage/myapp.lua + :language: lua + :start-after: delete_all_configs + :end-at: delete('/') + :dedent: - * ``target`` -- one of the following string values: ``revision``, ``mod_revision``, ``value``, ``count`` - * ``operator`` -- a string value: ``eq``, ``ne``, ``gt``, ``lt``, ``ge``, ``le`` or its symbolic equivalent, for example, ``==``, ``!=``, ``>`` - * ``value`` -- an unsigned or string value to compare - * ``path`` (optional) -- a string value: can be a path with the ``mod_revision`` and ``value`` target or a path/prefix with the ``count`` target + **Client API examples:** - * ``on_success``: a list with operations to execute if all predicates in the list evaluate to ``true`` + The example below shows how to delete a configuration stored by the ``/myapp/config/all`` path: - * ``on_failure``: a list with operations to execute if any of a predicate evaluates to ``false`` + .. literalinclude:: /code_snippets/snippets/centralized_config/instances.enabled/tarantool_config_storage/myapp_client.lua + :language: lua + :start-after: delete_config + :end-at: delete('/myapp/config/all') + :dedent: - :return: a table containing the following fields: + In this example, all configuration are deleted: - * ``data``: a table containing response data: + .. literalinclude:: /code_snippets/snippets/centralized_config/instances.enabled/tarantool_config_storage/myapp_client.lua + :language: lua + :start-after: delete_all_configs + :end-at: delete('/') + :dedent: - * ``responses``: the list of responses for all operations - * ``is_success``: a boolean value indicating whether the predicate is evaluated to ``true`` + Examples on GitHub: `tarantool_config_storage `_ - * ``revision``: a revision after performing the operation - :rtype: table + .. _config_storage_object_api_reference_info: + + .. method:: info() + + Get information about an instance's connection state. + + :return: a table containing the following fields: + + * ``status``: a connection status, which can be one of the following: + + * ``connected``: if any instance from the quorum is available to the current instance + * ``disconnected``: if the current instance doesn't have a connection with the quorum + + :rtype: table + + + .. _config_storage_object_api_reference_txn: + + .. method:: txn(request) + + Make an atomic request. + + :param table request: a table containing the following optional fields: + + * ``predicates``: a list of predicates to check. Each predicate is a list that contains: + + .. code-block:: none + + {target, operator, value[, path]} + + * ``target`` -- one of the following string values: ``revision``, ``mod_revision``, ``value``, ``count`` + * ``operator`` -- a string value: ``eq``, ``ne``, ``gt``, ``lt``, ``ge``, ``le`` or its symbolic equivalent, for example, ``==``, ``!=``, ``>`` + * ``value`` -- an unsigned or string value to compare + * ``path`` (optional) -- a string value: can be a path with the ``mod_revision`` and ``value`` target or a path/prefix with the ``count`` target + + * ``on_success``: a list with operations to execute if all predicates in the list evaluate to ``true`` + + * ``on_failure``: a list with operations to execute if any of a predicate evaluates to ``false`` + + :return: a table containing the following fields: + + * ``data``: a table containing response data: + + * ``responses``: the list of responses for all operations + * ``is_success``: a boolean value indicating whether the predicate is evaluated to ``true`` + + * ``revision``: a revision after performing the operation + + :rtype: table + + **Server API example:** + + .. literalinclude:: /code_snippets/snippets/centralized_config/instances.enabled/tarantool_config_storage/myapp.lua + :language: lua + :start-at: config.storage.txn + :end-at: }) + :dedent: - **Example:** + **Client API example:** - .. literalinclude:: /code_snippets/snippets/centralized_config/instances.enabled/tarantool_config_storage/myapp.lua - :language: lua - :start-at: config.storage.txn - :end-at: }) - :dedent: + .. literalinclude:: /code_snippets/snippets/centralized_config/instances.enabled/tarantool_config_storage/myapp_client.lua + :language: lua + :start-at: config.storage.txn + :end-at: }) + :dedent: - Example on GitHub: `tarantool_config_storage `_ + Examples on GitHub: `tarantool_config_storage `_ .. toctree:: :maxdepth: 1