Add `config.storage` client and config.storage TTL option #5116

georgiy-belyanin · 2025-05-15T16:29:50Z

This patchset focuses on updates in th config Lua module reference related to
config.storage.

The first patch adds documentation for the config.storage_client module.
The module allows one to connect to a remote config.storage cluster and
use it as a key-value storage.

The examples on connecting to a config.storage instance via iproto has
been changed to an example on connecting to multiple config.storage
instances using the config.storage client and interacting with a
config.storage cluster.

Closes #4734

The second patch adds config.storage TTL option allowing one to specify a
time-to-live for the key in config.storage.

Closes https://github.com/tarantool/enterprise_doc/issues/281

This patch adds documentation for the `config.storage_client` module. The module allows one to connect to a remote config.storage cluster and use it as a key-value storage. The examples on connecting to a config.storage instance via iproto has been changed to an example on connecting to multiple config.storage instances using the config.storage client and interacting with a config.storage cluster. Closes #4734

This patch adds a time-to-live (TTL) option to `config.storage` API methods. This option allows one to put keys that will expire when the passed time passes. Closes tarantool/enterprise_doc#281

Totktonada · 2025-05-16T14:34:03Z

doc/reference/reference_lua/config.rst

    :param string value: a value to put
+    :param table opts:   a table containing the following optional fields:
+
+                            *   ``ttl`` (since :doc:`3.2.0 </release/3.2.0>`, default: unset): time-to-live in seconds, if nil or not set the key won't expire, may issue an error if set on config.storage running old schema, see :ref:`config.storage.info <config_storage_api_reference_info>`.


AFAIR, we discussed a lot the following corner cases:

If a key exists and has no TTL, what put of this key with TTL do?

Vice versa: if the key exists and has TTL, what put of this key without TTL do?

Next, if a key has TTL that expires at time T and we attempt to put this key with a TTL that expires at time T1 < T, whether the expire occurs on T1 or T? How about T2 > T?

I would like if the API documentation would describe a behavior in these scenarios.

I have changed the doc as follows.

--- a/doc/reference/reference_lua/config.rst +++ b/doc/reference/reference_lua/config.rst @@ -403,7 +403,7 @@ The ``config.storage`` API allows you to interact with a Tarantool-based :ref:`c :param string value: a value to put :param table opts: a table containing the following optional fields: - * ``ttl`` (since :doc:`3.2.0 </release/3.2.0>`, default: unset): time-to-live in seconds, if nil or not set the key won't expire, may issue an error if set on config.storage running old schema, see :ref:`config.storage.info <config_storage_api_reference_info>`. + * ``ttl`` (since :doc:`3.2.0 </release/3.2.0>`, default: unset): time-to-live in seconds. If nil or not set the key won't expire. If the path is already present its deadline is calculated for the new time-to-live value no matter if it has been unset, later, or earlier than the new one. The option may issue an error if set on config.storage running old schema, see :ref:`config.storage.info <config_storage_api_reference_info>`. :return: a table containing the following fields:

Totktonada · 2025-05-16T15:53:33Z

doc/reference/reference_lua/config.rst

+:return:    a table containing the following fields:
+
+            *   ``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
+
+            *   ``revision``: a revision after performing the operation


TBH, it is not very clear from this description, whether data contains the {path = <...>, mod_revision = <...>, value = <...>} mapping or an array of them. Since the call suport both point and prefix requests, I guess that it is either an array or a mapping of mappings. Anyway, I think that it would be nice to make it clear.

This is not really to this PR, because the description is the same as for the server API. Feel free to ignore.

I want to ignore it in this patch.

Totktonada · 2025-05-16T15:58:03Z

doc/reference/reference_lua/config.rst

+:param string path: a path to put the value by
+:param string value: a value to put


Don't know why, but it seems the rendering fails here:

And in other places too.

Totktonada

Thank you for working on it!

AArdeev

Надо потом на пересобранное посмотреть, отработают ли ссылки на return tyoe table

AArdeev · 2025-10-08T12:40:59Z

doc/platform/configuration/configuration_etcd.rst

 -   ``timeout`` specifies the interval (in seconds) to perform the status check of a configuration storage.
 -   ``reconnect_after`` specifies how much time to wait (in seconds) before reconnecting to a configuration storage.

+You might use :ref:`config.storage_client <config_storage_client_api_reference>` API for connecting and controlling a remote config.storage cluster.


You can use the :ref:config.storage_client <config_storage_client_api_reference> API to connect to and control a remote config.storage cluster.

AArdeev · 2025-10-08T12:42:00Z

doc/reference/reference_lua/config.rst


-By using the ``config.storage`` :ref:`role <configuration_application_roles>`, you can set up a Tarantool-based :ref:`centralized configuration storage <configuration_etcd>` and interact with this storage using the ``config`` module API.
-
+By using the ``config.storage`` :ref:`role <configuration_application_roles>`, you can set up a Tarantool-based :ref:`centralized configuration storage <configuration_etcd>` and interact with this storage using the ``config`` module API. ``config.storage_client`` allows to connect to such storages and to interact with them from other Tarantool instances.


By using the config.storage :ref:role <configuration_application_roles>, you can set up a Tarantool-based :ref:centralized configuration storage <configuration_etcd> and interact with this storage using the config module API. config.storage_client allows connecting to such storages and interacting with them from other Tarantool instances.

AArdeev · 2025-10-08T12:44:47Z

doc/reference/reference_lua/config.rst

+            -   Connect to a remote config.storage cluster
+
+        *   -   :ref:`<config.storage client>:put() <config_storage_client_api_reference_put>`
+            -   Put a value by the specified path


Store a value at the specified path

AArdeev · 2025-10-08T12:45:33Z

doc/reference/reference_lua/config.rst

+            -   Put a value by the specified path
+
+        *   -   :ref:`<config.storage client>:get() <config_storage_client_api_reference_get>`
+            -   Get a value stored by the specified path


Get a value stored at the specified path

AArdeev · 2025-10-08T12:45:50Z

doc/reference/reference_lua/config.rst

+            -   Get a value stored by the specified path
+
+        *   -   :ref:`<config.storage client>:delete() <config_storage_client_api_reference_delete>`
+            -   Delete a value stored by the specified path


Delete a value stored at the specified path

AArdeev · 2025-10-09T05:35:55Z

doc/reference/reference_lua/config.rst

+
+.. function:: <config.storage client>:on_disconnect(func)
+
+Set a trigger for execution when the established connection to a config.storage cluster instance is closed. This also includes the cases when the config.storage client loses connection to a specific instance but automatically re-establishes it to another available one. Execution stops after a config.storage client is explicitly closed, or once the Lua garbage collector removes it. Calling this method replaces an old disconnect trigger with a new one if set.


Set a trigger for execution when the established connection to a config.storage cluster instance is closed. This also includes cases when
the config.storage client loses connection to a specific instance but automatically re-establishes it to another available one.
Execution stops after the config.storage client is explicitly closed, or once the Lua garbage collector removes it. Calling this method replaces any existing disconnect trigger with a new one if set.

AArdeev · 2025-10-09T05:36:33Z

doc/reference/reference_lua/config.rst

+
+.. function:: <config.storage client>:watch(path_or_event_key, func)
+
+Subscribe to config.storage events broadcast. You might use one of the following events.


Subscribe to the config.storage events broadcast. The following events are available:

AArdeev · 2025-10-09T05:38:11Z

doc/reference/reference_lua/config.rst

+* ``info`` is an event corresponding to the update on the client information.
+* ``/path/to/key`` or ``/prefix/to/watch/`` is an event that corresponds to the updates of the specific key or of multiple keys having the specified prefix.


info corresponds to the update on the client information.

/path/to/key or /prefix/to/watch/ corresponds to the updates of the specific key or of multiple keys having the specified prefix.

AArdeev · 2025-10-09T05:42:21Z

doc/reference/reference_lua/config.rst

+
+To read more about watchers, see the :ref:`Functions for watchers <box-watchers>` section.
+
+The method has the same syntax as :ref:`box.watch() <box-watch>` and :ref:`conn:watch() <conn-watch>` functions. In fact, the call ``<config.storage client>:watch('<key>', f)`` internally subscribes to ``config.storage.<key>`` or to ``config.storage:<path>`` event broadcast through :ref:`IPROTO <box_protocol-id>`.


The method has the same syntax as :ref:box.watch() <box-watch> and :ref:conn:watch() <conn-watch> functions. In fact, the
<config.storage client>:watch('<key>', f) call internally subscribes to config.storage.<key> or config.storage:<path> event
broadcast through :ref:IPROTO <box_protocol-id>.

AArdeev · 2025-10-09T05:44:50Z

doc/reference/reference_lua/config.rst

+    Keep in mind that garbage collection of a watcher handle doesn't lead to the watcher's destruction.
+    In this case, the watcher remains registered.
+    It is okay to discard the result of ``watch`` function if the watcher will never be unregistered.


Garbage collection of a watcher handle does not lead to the watcher's destruction. In this case, the watcher remains registered. You can discard the result of the ``watch`` function if the watcher is not going to be unregistered.

georgiy-belyanin mentioned this pull request May 15, 2025

Add config.storage_client documentation #4734

Closed

github-actions bot temporarily deployed to branch-config-storage-client May 15, 2025 16:31 Destroyed

georgiy-belyanin added 2 commits May 15, 2025 20:35

Add config.storage TTL option

c41464a

This patch adds a time-to-live (TTL) option to `config.storage` API methods. This option allows one to put keys that will expire when the passed time passes. Closes tarantool/enterprise_doc#281

georgiy-belyanin force-pushed the gbelyanin/config-storage-client branch from 870e4a7 to c41464a Compare May 15, 2025 17:35

github-actions bot deployed to branch-config-storage-client May 15, 2025 17:37 View deployment

Totktonada reviewed May 16, 2025

View reviewed changes

Totktonada approved these changes May 16, 2025

View reviewed changes

Totktonada assigned georgiy-belyanin May 16, 2025

AArdeev reviewed Oct 9, 2025

View reviewed changes

		:param string path: a path to put the value by
		:param string value: a value to put


		By using the ``config.storage`` :ref:`role <configuration_application_roles>`, you can set up a Tarantool-based :ref:`centralized configuration storage <configuration_etcd>` and interact with this storage using the ``config`` module API.

		By using the ``config.storage`` :ref:`role <configuration_application_roles>`, you can set up a Tarantool-based :ref:`centralized configuration storage <configuration_etcd>` and interact with this storage using the ``config`` module API. ``config.storage_client`` allows to connect to such storages and to interact with them from other Tarantool instances.


		.. function:: <config.storage client>:on_disconnect(func)

		Set a trigger for execution when the established connection to a config.storage cluster instance is closed. This also includes the cases when the config.storage client loses connection to a specific instance but automatically re-establishes it to another available one. Execution stops after a config.storage client is explicitly closed, or once the Lua garbage collector removes it. Calling this method replaces an old disconnect trigger with a new one if set.


		.. function:: <config.storage client>:watch(path_or_event_key, func)

		Subscribe to config.storage events broadcast. You might use one of the following events.

		* ``info`` is an event corresponding to the update on the client information.
		* ``/path/to/key`` or ``/prefix/to/watch/`` is an event that corresponds to the updates of the specific key or of multiple keys having the specified prefix.


		To read more about watchers, see the :ref:`Functions for watchers <box-watchers>` section.

		The method has the same syntax as :ref:`box.watch() <box-watch>` and :ref:`conn:watch() <conn-watch>` functions. In fact, the call ``<config.storage client>:watch('<key>', f)`` internally subscribes to ``config.storage.<key>`` or to ``config.storage:<path>`` event broadcast through :ref:`IPROTO <box_protocol-id>`.

Add config.storage client and config.storage TTL option #5116

Are you sure you want to change the base?

Add config.storage client and config.storage TTL option #5116

Uh oh!

Conversation

georgiy-belyanin commented May 15, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Totktonada left a comment

Choose a reason for hiding this comment

Uh oh!

AArdeev left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Add `config.storage` client and config.storage TTL option #5116

Add `config.storage` client and config.storage TTL option #5116