Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: latest
Choose a base branch
from
Open

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

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
11c2862
Add `config.storage_client` documentation
georgiy-belyanin Jan 10, 2025
c41464a
Add `config.storage` TTL option
georgiy-belyanin May 15, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
69 changes: 67 additions & 2 deletions doc/reference/reference_lua/config.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -395,12 +395,16 @@ The ``config.storage`` API allows you to interact with a Tarantool-based :ref:`c

.. _config_storage_api_reference_put:

.. function:: put(path, value)
.. function:: put(path, value, opts)

Put a value by the specified path.

:param string path: a path to put the value by
: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>`.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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:

Comment on lines +404 to +406
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more. 

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



:return: a table containing the following fields:

Expand Down Expand Up @@ -516,9 +520,25 @@ The ``config.storage`` API allows you to interact with a Tarantool-based :ref:`c
* ``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

* ``features`` (since :doc:`3.2.0 </release/3.2.0>`): a table of features config.storage supports, may include the following:

* ``ttl``: true if key TTL (time-to-live) is supported, false otherwise if the schema hasn't been upgraded yet
Comment on lines +523 to +525
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more. 

            *   ``features`` (since :doc:`3.2.0 </release/3.2.0>`): a table of features that ``config.storage`` supports. May include the following:

                * ``ttl``: ``true`` if key TTL (time-to-live) is supported; ``false`` if the schema has not been upgraded yet



:rtype: table


**Example:**

The example below shows how to check whether config.storage supports keys TTL:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The example below shows how to check whether config.storage supports the TTL key:


.. code-block:: lua

local info = config.storage.info
if info.features == nil or not info.features.ttl then
error('...')
end

.. _config_storage_api_reference_txn:

.. function:: txn(request)
Expand All @@ -542,6 +562,17 @@ The ``config.storage`` API allows you to interact with a Tarantool-based :ref:`c

* ``on_failure``: a list with operations to execute if any of a predicate evaluates to ``false``

Operations in ``on_success`` and ``on_failure`` follow the format:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Operations in on_success and on_failure follow the format below:


.. code-block:: none

{operation, key_or_path[, value][, opts]}

* ``operation``: one of ``'put'``, ``'get'``, ``'delete'``
* ``opts``: a table containing optional fields for the operations:

* ``ttl`` (since :doc:`3.2.0 </release/3.2.0>`, default: unset): time-to-live for a key in seconds, if nil or not set the key won't expire
Comment on lines +571 to +574
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more. 

        * ``operation``: may take one of the following:
           * ``'put'``
           * ``'get'``
           * ``'delete'``
        * ``opts``:  a table containing the following fields for the operations:

                        *   ``ttl`` (since :doc:`3.2.0 </release/3.2.0>`, optional): time-to-live for a key in seconds. If ``nil`` or not set the key won't expire


:return: a table containing the following fields:

* ``data``: a table containing response data:
Expand Down Expand Up @@ -608,12 +639,17 @@ Examples on GitHub: `config_storage <https://github.com/tarantool/doc/tree/lates

.. _config_storage_client_api_reference_put:

.. function:: <config.storage client>:put(path, value)
.. function:: <config.storage client>:put(path, value, opts)

Put a value by the specified path to remote config.storage.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Put a value by the specified path to a remote config.storage.


:param string path: a path to put the value by
: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 client>.info <config_storage_client_api_reference_info>`.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more. 

                *   ``ttl`` (since :doc:`3.2.0 </release/3.2.0>): time-to-live in seconds. If ``nil`` or not set the key won't expire.
                     May issue an error if set on a ``config.storage`` running an old schema, see :ref:`<config.storage client>.info <config_storage_client_api_reference_info>`.




:return: a table containing the following fields:

Expand Down Expand Up @@ -727,9 +763,26 @@ Get information about a connection state to the config.storage cluster.
* ``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

* ``features`` (since :doc:`3.2.0 </release/3.2.0>`): a table of features config.storage supports, may include the following:

* ``ttl``: true if key TTL (time-to-live) is supported, false otherwise if the schema hasn't been upgraded yet
Comment on lines +766 to +768
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more. 

        *   ``features`` (since :doc:`3.2.0 </release/3.2.0>`): a table of features that ``config.storage`` supports. May include the following:

            * ``ttl``: ``true`` if key TTL (time-to-live) is supported; ``false`` if the schema hasn't been upgraded yet



:rtype: table


**Example:**

The example below shows how to check whether remote config.storage supports keys TTL:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The example below shows how to check whether the remote config.storage supports the TTL key:


.. code-block:: lua

local info = storage_client.info
if info.features == nil or not info.features.ttl then
error('...')
end


.. _config_storage_client_api_reference_txn:

.. function:: <config.storage client>:txn(request)
Expand All @@ -753,6 +806,18 @@ Make an atomic request on remote config.storage.

* ``on_failure``: a list with operations to execute if any of a predicate evaluates to ``false``
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more. 

                    * ``on_failure``: a list with operations to execute if any predicate evaluates to ``false``


Operations in ``on_success`` and ``on_failure`` follow the format:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more. 

    Operations in ``on_success`` and ``on_failure`` follow the format below:


.. code-block:: none

{operation, key_or_path[, value][, opts]}

* ``operation``: one of ``'put'``, ``'get'``, ``'delete'``
* ``opts``: a table containing optional fields for the operations:

* ``ttl`` (since :doc:`3.2.0 </release/3.2.0>`, default: unset): time-to-live for a key in seconds, if nil or not set the key won't expire
Comment on lines +815 to +818
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more. 

        * ``operation``: may take one of the following:
           * ``'put'``
           * ``'get'``
           * ``'delete'``
        * ``opts``:  a table containing the following fields for the operations:

                        *   ``ttl`` (since :doc:`3.2.0 </release/3.2.0>`, optional): time-to-live for a key in seconds. If ``nil`` or not set the key won't expire



:return: a table containing the following fields:

* ``data``: a table containing response data:
Expand Down