Skip to content
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.

Commit 0a1b4ee

Browse files
georgiy-belyaningeorgiy-belyanin
committedMay 13, 2025·
Add config.storage_client documentation
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. Examples for working both with Tarantool config.storage server API and Tarantool config.storage client API are provided side by side since they share quite the same API. 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.
1 parent 959c606 commit 0a1b4ee

File tree

3 files changed

+399
-113
lines changed

3 files changed

+399
-113
lines changed
 

‎doc/code_snippets/snippets/centralized_config/instances.enabled/config_storage/myapp.lua

Lines changed: 83 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,84 @@
1-
net_box = require('net.box')
2-
local conn = net_box.connect('127.0.0.1:4401')
31
local log = require('log')
4-
conn:watch('config.storage:/myapp/config/all', function(key, value)
5-
log.info("Configuration stored by the '/myapp/config/all' key is changed")
6-
end)
2+
config = require('config')
3+
4+
storage_client = config.storage_client.connect({
5+
{
6+
uri = '127.0.0.1:4401',
7+
login = 'sampleuser',
8+
password = '123456',
9+
},
10+
{
11+
uri = '127.0.0.1:4402',
12+
login = 'sampleuser',
13+
password = '123456',
14+
},
15+
{
16+
uri = '127.0.0.1:4403',
17+
login = 'sampleuser',
18+
password = '123456',
19+
},
20+
})
21+
22+
function register_watchers()
23+
storage_client:watch('/myapp/config/all', function(_, revision)
24+
log.info("Configuration stored by the '/myapp/config/all' key is " ..
25+
"changed. New revision number is %d.", revision)
26+
end)
27+
end
28+
29+
register_watchers()
30+
31+
function connect_to_configured_storage()
32+
-- `config.storage.endpoints` configuration section can be
33+
-- passed directly as `connect()` options to connect to the
34+
-- configured config.storage cluster.
35+
local endpoints = config:get('config.storage.endpoints')
36+
local storage_client = config.storage_client.connect(endpoints)
37+
38+
return storage_client
39+
end
40+
41+
function put_config()
42+
local fio = require('fio')
43+
local cluster_config_handle = fio.open('../../source.yaml')
44+
local cluster_config = cluster_config_handle:read()
45+
local response = storage_client:put('/myapp/config/all', cluster_config)
46+
cluster_config_handle:close()
47+
48+
return response
49+
end
50+
51+
function get_config_by_path()
52+
local response = storage_client:get('/myapp/config/all')
53+
54+
return response
55+
end
56+
57+
function get_config_by_prefix()
58+
local response = storage_client:get('/myapp/')
59+
60+
return response
61+
end
62+
63+
function make_txn_request()
64+
-- Execute an atomic request on the config.storage cluster.
65+
local response = storage_client:txn({
66+
predicates = { { 'value', '==', 'v0', '/myapp/config/all' } },
67+
on_success = { { 'put', '/myapp/config/all', 'v1' } },
68+
on_failure = { { 'get', '/myapp/config/all' } }
69+
})
70+
71+
return response
72+
end
73+
74+
function delete_config()
75+
local response = storage_client:delete('/myapp/config/all')
76+
77+
return response
78+
end
79+
80+
function delete_all_configs()
81+
local response = storage_client:delete('/')
82+
83+
return response
84+
end

‎doc/platform/configuration/configuration_etcd.rst

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -260,6 +260,8 @@ In the example below, the following options are specified:
260260
- ``timeout`` specifies the interval (in seconds) to perform the status check of a configuration storage.
261261
- ``reconnect_after`` specifies how much time to wait (in seconds) before reconnecting to a configuration storage.
262262

263+
You might use :ref:`config.storage_client <config_storage_client_api_reference>` API for connecting and controlling a remote config.storage cluster.
264+
263265
You can find the full example here: `config_storage <https://github.com/tarantool/doc/tree/latest/doc/code_snippets/snippets/centralized_config/instances.enabled/config_storage>`_.
264266

265267

‎doc/reference/reference_lua/config.rst

Lines changed: 314 additions & 108 deletions
Original file line numberDiff line numberDiff line change
@@ -8,8 +8,7 @@ Module config
88
The ``config`` module provides the ability to work with an instance's configuration.
99
For example, you can determine whether the current instance is up and running without errors after applying the :ref:`cluster's configuration <configuration_overview>`.
1010

11-
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.
12-
11+
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.
1312

1413
.. _config_module_loading:
1514

@@ -63,22 +62,52 @@ API Reference
6362
* - **config.storage API**
6463
-
6564

66-
* - :ref:`config.storage.put() <config_storage_api_reference_put>`
65+
* - :ref:`config.storage <config_storage_api_reference>`
66+
- Server API for interacting with config.storage clusters
67+
68+
* - :ref:`config.storage_client <config_storage_client_api_reference>`
69+
- Client API for interacting with config.storage clusters
70+
71+
* - :ref:`config.storage_client.connect() <config_storage_client_api_reference_connect>`
72+
- Connect to a remote config.storage cluster
73+
74+
* - :ref:`<config.storage server>:put() <config_storage_object_api_reference_put>` |br|
75+
:ref:`<config.storage client>:put() <config_storage_object_api_reference_put>`
6776
- Put a value by the specified path
6877

69-
* - :ref:`config.storage.get() <config_storage_api_reference_get>`
78+
* - :ref:`<config.storage server>:get() <config_storage_object_api_reference_get>` |br|
79+
:ref:`<config.storage client>:get() <config_storage_object_api_reference_get>`
7080
- Get a value stored by the specified path
7181

72-
* - :ref:`config.storage.delete() <config_storage_api_reference_delete>`
82+
* - :ref:`<config.storage server>:delete() <config_storage_object_api_reference_delete>` |br|
83+
:ref:`<config.storage client>:delete() <config_storage_object_api_reference_delete>`
7384
- Delete a value stored by the specified path
7485

75-
* - :ref:`config.storage.info() <config_storage_api_reference_info>`
86+
* - :ref:`<config.storage server>:info() <config_storage_object_api_reference_info>` |br|
87+
:ref:`<config.storage client>:info() <config_storage_object_api_reference_info>`
7688
- Get information about an instance's connection state
7789

78-
* - :ref:`config.storage.txn() <config_storage_api_reference_txn>`
90+
* - :ref:`<config.storage server>:txn() <config_storage_object_api_reference_txn>` |br|
91+
:ref:`<config.storage client>:txn() <config_storage_object_api_reference_txn>`
7992
- Make an atomic request
8093

94+
* - :ref:`<config.storage client>:is_connected() <config_storage_client_api_reference_is_connected>`
95+
- Check if there is active connection to a config.storage cluster
96+
97+
* - :ref:`<config.storage client>:close() <config_storage_client_api_reference_close>`
98+
- Close connection to a config.storage cluster
8199

100+
* - :ref:`<config.storage client>:is_closed() <config_storage_client_api_reference_is_closed>`
101+
- Check whether the connection has been closed by a user
102+
103+
* - :ref:`<config.storage client>:reconnect() <config_storage_client_api_reference_reconnect>`
104+
- Reconnect to one of the config.storage instances after calling ``close()``
105+
106+
* - :ref:`<config.storage client>:on_disconnect() <config_storage_client_api_reference_on_disconnect>`
107+
- Define a config.storage cluster disconnect trigger
108+
109+
* - :ref:`<config.storage client>:watch() <config_storage_client_api_reference_watch>`
110+
- Subscribe to config.storage events broadcast
82111

83112
.. _config_api_reference:
84113

@@ -351,178 +380,355 @@ config API
351380
config.storage API
352381
~~~~~~~~~~~~~~~~~~
353382

354-
The ``config.storage`` API allows you to interact with a Tarantool-based :ref:`centralized configuration storage <configuration_etcd>`.
383+
The ``config.storage`` and ``config.storage_client`` API allows you to interact with Tarantool-based :ref:`centralized configuration storage <configuration_etcd>`.
384+
385+
.. class:: config.storage
386+
387+
If you configure a replicaset as :ref:`Tarantool-based centralized configuration storage <centralized_configuration_storage_tarantool_configure>` by specifying a ``config.storage`` role (see :ref:`configuring roles <configuration_reference_roles>`) the ``config.storage`` object provides ``<config.storage server>`` methods to interact with a key-value storage, see Server API examples below.
355388

356-
.. module:: config.storage
389+
.. _config_storage_client_api_reference:
357390

358-
.. _config_storage_api_reference_put:
391+
.. class:: config.storage_client
359392

360-
.. function:: put(path, value)
393+
The ``config.storage_client`` API allows you to connect to a remote replica set :ref:`configured as a Tarantool-based centralized configuration storage <configuration_etcd>` and interact with it as a key-value storage, see Client API examples below.
361394

362-
Put a value by the specified path.
395+
.. _config_storage_client_api_reference_connect:
363396

364-
:param string path: a path to put the value by
365-
:param string value: a value to put
397+
.. function:: connect(endpoints[, options])
366398

367-
:return: a table containing the following fields:
399+
Connect to a remote config.storage cluster.
368400

369-
* ``revision``: a revision after performing the operation
401+
:param table endpoints: table of config.storage instance URIs
402+
:param table options: ``timeout`` - number, connect & call timeout (default: ``nil``, unset)
403+
404+
:return: a <config.storage client> object
370405

371406
:rtype: table
372407

373-
**Example:**
408+
The example below shows how to connect to a specific config.storage cluster:
374409

375-
The example below shows how to read a configuration stored in the ``source.yaml`` file using the :ref:`fio module <fio-module>` API and put this configuration by the ``/myapp/config/all`` path:
410+
.. literalinclude:: /code_snippets/snippets/centralized_config/instances.enabled/config_storage/myapp.lua
411+
:language: lua
412+
:start-after: config = require
413+
:end-at: })
414+
:dedent:
376415

377-
.. literalinclude:: /code_snippets/snippets/centralized_config/instances.enabled/tarantool_config_storage/myapp.lua
378-
:language: lua
379-
:start-after: function put_config
380-
:end-at: cluster_config_handle:close()
381-
:dedent:
416+
The example below shows how to connect to a config storage cluster configured as the :ref:`centralized configuration storage <configuration_etcd>` in the :ref:`config.storage <configuration_reference_config_storage>` option:
382417

383-
Example on GitHub: `tarantool_config_storage <https://github.com/tarantool/doc/tree/latest/doc/code_snippets/snippets/centralized_config/instances.enabled/tarantool_config_storage>`_
418+
.. literalinclude:: /code_snippets/snippets/centralized_config/instances.enabled/config_storage/myapp.lua
419+
:language: lua
420+
:start-after: function connect_to_configured_storage
421+
:end-at: config.storage_client.connect
422+
:dedent:
384423

424+
Examples on GitHub: `config_storage <https://github.com/tarantool/doc/tree/latest/doc/code_snippets/snippets/centralized_config/instances.enabled/config_storage>`_
385425

386-
.. _config_storage_api_reference_get:
426+
.. _config_storage_object_api_reference_put:
387427

388-
.. function:: get(path)
428+
.. function:: <config.storage server>.put(path, value)
429+
.. function:: <config.storage client>:put(path, value)
389430

390-
Get a value stored by the specified path or prefix.
431+
Put a value by the specified path.
391432

392-
:param string path: a path or prefix to get a value by; prefixes end with ``/``
433+
:param string path: a path to put the value by
434+
:param string value: a value to put
393435

394-
:return: a table containing the following fields:
436+
:return: a table containing the following fields:
395437

396-
* ``data``: a table containing the information about the value:
438+
* ``revision``: a revision after performing the operation
397439

398-
* ``path``: a path
399-
* ``mod_revision``: the last revision at which this value was modified
400-
* ``value:``: a value
440+
:rtype: table
401441

402-
* ``revision``: a revision after performing the operation
442+
**Server API example:**
403443

404-
:rtype: table
444+
The example below shows how to read a configuration stored in the ``source.yaml`` file using the :ref:`fio module <fio-module>` API and put this configuration by the ``/myapp/config/all`` path:
405445

406-
**Examples:**
446+
.. literalinclude:: /code_snippets/snippets/centralized_config/instances.enabled/tarantool_config_storage/myapp.lua
447+
:language: lua
448+
:start-after: function put_config
449+
:end-at: cluster_config_handle:close()
450+
:dedent:
407451

408-
The example below shows how to get a configuration stored by the ``/myapp/config/all`` path:
452+
Examples on GitHub: `tarantool_config_storage <https://github.com/tarantool/doc/tree/latest/doc/code_snippets/snippets/centralized_config/instances.enabled/tarantool_config_storage>`_
409453

410-
.. literalinclude:: /code_snippets/snippets/centralized_config/instances.enabled/tarantool_config_storage/myapp.lua
411-
:language: lua
412-
:start-after: get_config_by_path
413-
:end-at: get('/myapp/config/all')
414-
:dedent:
454+
**Client API example:**
415455

416-
This example shows how to get all configurations stored by the ``/myapp/`` prefix:
456+
The example below shows how to read a configuration stored in the ``source.yaml`` file using the :ref:`fio module <fio-module>` API and put this configuration by the ``/myapp/config/all`` path:
417457

418-
.. literalinclude:: /code_snippets/snippets/centralized_config/instances.enabled/tarantool_config_storage/myapp.lua
419-
:language: lua
420-
:start-after: get_config_by_prefix
421-
:end-at: get('/myapp/')
422-
:dedent:
458+
.. literalinclude:: /code_snippets/snippets/centralized_config/instances.enabled/config_storage/myapp.lua
459+
:language: lua
460+
:start-after: function put_config
461+
:end-at: cluster_config_handle:close()
462+
:dedent:
423463

424-
Example on GitHub: `tarantool_config_storage <https://github.com/tarantool/doc/tree/latest/doc/code_snippets/snippets/centralized_config/instances.enabled/tarantool_config_storage>`_
464+
Examples on GitHub: `config_storage <https://github.com/tarantool/doc/tree/latest/doc/code_snippets/snippets/centralized_config/instances.enabled/config_storage>`_
425465

426-
.. _config_storage_api_reference_delete:
466+
.. _config_storage_object_api_reference_get:
427467

428-
.. function:: delete(path)
468+
.. function:: <config.storage server>.get(path)
469+
.. function:: <config.storage client>:get(path)
429470

430-
Delete a value stored by the specified path or prefix.
471+
Get a value stored by the specified path or prefix.
431472

432-
:param string path: a path or prefix to delete the value by; prefixes end with ``/``
473+
:param string path: a path or prefix to get a value by; prefixes end with ``/``
433474

434-
:return: a table containing the following fields:
475+
:return: a table containing the following fields:
435476

436-
* ``data``: a table containing the information about the value:
477+
* ``data``: a table containing the information about the value:
437478

438-
* ``path``: a path
439-
* ``mod_revision``: the last revision at which this value was modified
440-
* ``value:``: a value
479+
* ``path``: a path
480+
* ``mod_revision``: the last revision at which this value was modified
481+
* ``value:``: a value
441482

442-
* ``revision``: a revision after performing the operation
483+
* ``revision``: a revision after performing the operation
443484

444-
:rtype: table
485+
:rtype: table
445486

446-
**Examples:**
487+
**Server API examples:**
447488

448-
The example below shows how to delete a configuration stored by the ``/myapp/config/all`` path:
489+
The example below shows how to get a configuration stored by the ``/myapp/config/all`` path:
449490

450-
.. literalinclude:: /code_snippets/snippets/centralized_config/instances.enabled/tarantool_config_storage/myapp.lua
451-
:language: lua
452-
:start-after: delete_config
453-
:end-at: delete('/myapp/config/all')
454-
:dedent:
491+
.. literalinclude:: /code_snippets/snippets/centralized_config/instances.enabled/tarantool_config_storage/myapp.lua
492+
:language: lua
493+
:start-after: get_config_by_path
494+
:end-at: get('/myapp/config/all')
495+
:dedent:
455496

456-
In this example, all configuration are deleted:
497+
This example shows how to get all configurations stored by the ``/myapp/`` prefix:
457498

458-
.. literalinclude:: /code_snippets/snippets/centralized_config/instances.enabled/tarantool_config_storage/myapp.lua
459-
:language: lua
460-
:start-after: delete_all_configs
461-
:end-at: delete('/')
462-
:dedent:
499+
.. literalinclude:: /code_snippets/snippets/centralized_config/instances.enabled/tarantool_config_storage/myapp.lua
500+
:language: lua
501+
:start-after: get_config_by_prefix
502+
:end-at: get('/myapp/')
503+
:dedent:
463504

464-
Example on GitHub: `tarantool_config_storage <https://github.com/tarantool/doc/tree/latest/doc/code_snippets/snippets/centralized_config/instances.enabled/tarantool_config_storage>`_
505+
Examples on GitHub: `tarantool_config_storage <https://github.com/tarantool/doc/tree/latest/doc/code_snippets/snippets/centralized_config/instances.enabled/tarantool_config_storage>`_
465506

507+
**Client API examples:**
466508

467-
.. _config_storage_api_reference_info:
509+
The example below shows how to get a configuration stored by the ``/myapp/config/all`` path on a remote config.storage cluster:
468510

469-
.. function:: info()
511+
.. literalinclude:: /code_snippets/snippets/centralized_config/instances.enabled/config_storage/myapp.lua
512+
:language: lua
513+
:start-after: get_config_by_path
514+
:end-at: get('/myapp/config/all')
515+
:dedent:
470516

471-
Get information about an instance's connection state.
517+
This example shows how to get all configurations stored by the ``/myapp/`` prefix on a remote config.storage cluster:
472518

473-
:return: a table containing the following fields:
519+
.. literalinclude:: /code_snippets/snippets/centralized_config/instances.enabled/config_storage/myapp.lua
520+
:language: lua
521+
:start-after: get_config_by_prefix
522+
:end-at: get('/myapp/')
523+
:dedent:
474524

475-
* ``status``: a connection status, which can be one of the following:
525+
Examples on GitHub: `config_storage <https://github.com/tarantool/doc/tree/latest/doc/code_snippets/snippets/centralized_config/instances.enabled/config_storage>`_
476526

477-
* ``connected``: if any instance from the quorum is available to the current instance
478-
* ``disconnected``: if the current instance doesn't have a connection with the quorum
527+
.. _config_storage_object_api_reference_delete:
479528

480-
:rtype: table
529+
.. function:: <config.storage server>.delete(path)
530+
.. function:: <config.storage client>:delete(path)
481531

532+
Delete a value stored by the specified path or prefix.
482533

483-
.. _config_storage_api_reference_txn:
534+
:param string path: a path or prefix to delete the value by; prefixes end with ``/``
484535

485-
.. function:: txn(request)
536+
:return: a table containing the following fields:
486537

487-
Make an atomic request.
538+
* ``data``: a table containing the information about the value:
488539

489-
:param table request: a table containing the following optional fields:
540+
* ``path``: a path
541+
* ``mod_revision``: the last revision at which this value was modified
542+
* ``value:``: a value
490543

491-
* ``predicates``: a list of predicates to check. Each predicate is a list that contains:
544+
* ``revision``: a revision after performing the operation
492545

493-
.. code-block:: none
546+
:rtype: table
494547

495-
{target, operator, value[, path]}
548+
**Server API examples:**
496549

497-
* ``target`` -- one of the following string values: ``revision``, ``mod_revision``, ``value``, ``count``
498-
* ``operator`` -- a string value: ``eq``, ``ne``, ``gt``, ``lt``, ``ge``, ``le`` or its symbolic equivalent, for example, ``==``, ``!=``, ``>``
499-
* ``value`` -- an unsigned or string value to compare
500-
* ``path`` (optional) -- a string value: can be a path with the ``mod_revision`` and ``value`` target or a path/prefix with the ``count`` target
550+
The example below shows how to delete a configuration stored by the ``/myapp/config/all`` path:
501551

502-
* ``on_success``: a list with operations to execute if all predicates in the list evaluate to ``true``
552+
.. literalinclude:: /code_snippets/snippets/centralized_config/instances.enabled/tarantool_config_storage/myapp.lua
553+
:language: lua
554+
:start-after: delete_config
555+
:end-at: delete('/myapp/config/all')
556+
:dedent:
503557

504-
* ``on_failure``: a list with operations to execute if any of a predicate evaluates to ``false``
558+
In this example, all configuration are deleted:
505559

506-
:return: a table containing the following fields:
560+
.. literalinclude:: /code_snippets/snippets/centralized_config/instances.enabled/tarantool_config_storage/myapp.lua
561+
:language: lua
562+
:start-after: delete_all_configs
563+
:end-at: delete('/')
564+
:dedent:
507565

508-
* ``data``: a table containing response data:
566+
Examples on GitHub: `tarantool_config_storage <https://github.com/tarantool/doc/tree/latest/doc/code_snippets/snippets/centralized_config/instances.enabled/tarantool_config_storage>`_
509567

510-
* ``responses``: the list of responses for all operations
511-
* ``is_success``: a boolean value indicating whether the predicate is evaluated to ``true``
568+
**Client API examples:**
512569

513-
* ``revision``: a revision after performing the operation
570+
The example below shows how to delete a configuration stored by the ``/myapp/config/all`` path:
514571

515-
:rtype: table
572+
.. literalinclude:: /code_snippets/snippets/centralized_config/instances.enabled/config_storage/myapp.lua
573+
:language: lua
574+
:start-after: delete_config
575+
:end-at: delete('/myapp/config/all')
576+
:dedent:
577+
578+
In this example, all values are deleted:
579+
580+
.. literalinclude:: /code_snippets/snippets/centralized_config/instances.enabled/config_storage/myapp.lua
581+
:language: lua
582+
:start-after: delete_all_configs
583+
:end-at: delete('/')
584+
:dedent:
585+
586+
Examples on GitHub: `config_storage <https://github.com/tarantool/doc/tree/latest/doc/code_snippets/snippets/centralized_config/instances.enabled/config_storage>`_
587+
588+
.. _config_storage_object_api_reference_info:
589+
590+
.. function:: <config.storage server>.info()
591+
.. function:: <config.storage client>:info()
592+
593+
Get information about an instance's connection state.
594+
595+
:return: a table containing the following fields:
596+
597+
* ``status``: a connection status, which can be one of the following:
598+
599+
* ``connected``: if any instance from the quorum is available to the current instance
600+
* ``disconnected``: if the current instance doesn't have a connection with the quorum
601+
602+
:rtype: table
603+
604+
605+
.. _config_storage_object_api_reference_txn:
606+
607+
.. function:: <config.storage server>.txn(request)
608+
.. function:: <config.storage client>:txn(request)
609+
610+
Make an atomic request.
611+
612+
:param table request: a table containing the following optional fields:
613+
614+
* ``predicates``: a list of predicates to check. Each predicate is a list that contains:
615+
616+
.. code-block:: none
617+
618+
{target, operator, value[, path]}
619+
620+
* ``target`` -- one of the following string values: ``revision``, ``mod_revision``, ``value``, ``count``
621+
* ``operator`` -- a string value: ``eq``, ``ne``, ``gt``, ``lt``, ``ge``, ``le`` or its symbolic equivalent, for example, ``==``, ``!=``, ``>``
622+
* ``value`` -- an unsigned or string value to compare
623+
* ``path`` (optional) -- a string value: can be a path with the ``mod_revision`` and ``value`` target or a path/prefix with the ``count`` target
624+
625+
* ``on_success``: a list with operations to execute if all predicates in the list evaluate to ``true``
626+
627+
* ``on_failure``: a list with operations to execute if any of a predicate evaluates to ``false``
628+
629+
:return: a table containing the following fields:
630+
631+
* ``data``: a table containing response data:
632+
633+
* ``responses``: the list of responses for all operations
634+
* ``is_success``: a boolean value indicating whether the predicate is evaluated to ``true``
635+
636+
* ``revision``: a revision after performing the operation
637+
638+
:rtype: table
639+
640+
**Server API example:**
641+
642+
.. literalinclude:: /code_snippets/snippets/centralized_config/instances.enabled/tarantool_config_storage/myapp.lua
643+
:language: lua
644+
:start-at: config.storage.txn
645+
:end-at: })
646+
:dedent:
647+
648+
Examples on GitHub: `tarantool_config_storage <https://github.com/tarantool/doc/tree/latest/doc/code_snippets/snippets/centralized_config/instances.enabled/tarantool_config_storage>`_
649+
650+
**Client API example:**
651+
652+
.. literalinclude:: /code_snippets/snippets/centralized_config/instances.enabled/config_storage/myapp.lua
653+
:language: lua
654+
:start-at: storage_client:txn
655+
:end-at: })
656+
:dedent:
657+
658+
Examples on GitHub: `config_storage <https://github.com/tarantool/doc/tree/latest/doc/code_snippets/snippets/centralized_config/instances.enabled/config_storage>`_
659+
660+
.. _config_storage_client_api_reference_is_connected:
661+
662+
.. function:: <config.storage client>:is_connected()
663+
664+
Show whether there is an active connection to a config.storage cluster.
665+
666+
:return: true if connected, false on failure.
667+
:rtype: boolean
668+
669+
.. _config_storage_client_api_reference_close:
670+
671+
.. function:: <config.storage client>:close()
672+
673+
Close existing connection to a config.storage cluster. Connection objects are destroyed by the Lua garbage collector, just like any other objects in Lua, so an explicit destruction is not mandatory. However, since ``close()`` is a system call, it is good programming practice to close a connection explicitly when it is no longer needed, to avoid lengthy stalls of the garbage collector.
674+
675+
Note connection to the config.storage will be re-established automatically if one of the remote config.storage client methods is called.
676+
677+
.. _config_storage_client_api_reference_is_closed:
678+
679+
.. function:: <config.storage client>:is_closed()
680+
681+
Show whether the connection has been closed by a user with ``close()``.
682+
683+
:return: true if closed, false on failure.
684+
:rtype: boolean
685+
686+
.. _config_storage_client_api_reference_reconnect:
687+
688+
.. function:: <config.storage client>:reconnect()
689+
690+
Reconnect to one of the config.storage instances after calling ``close()``.
691+
692+
.. _config_storage_client_api_reference_on_disconnect:
693+
694+
.. function:: <config.storage client>:on_disconnect(func)
695+
696+
Define 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.
697+
698+
.. _config_storage_client_api_reference_watch:
699+
700+
.. function:: <config.storage client>:watch(path_or_key, func)
701+
702+
Subscribe to config.storage events broadcast. You might use one of the following events.
703+
704+
* ``info`` is an event corresponding to the update on the client information.
705+
* ``/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.
706+
707+
:param string key: a key name of an event to subscribe to
708+
:param function func: a callback to invoke when the key value is updated
709+
:return: a watcher handle. The handle consists of one method -- ``unregister()``, which unregisters the watcher.
710+
711+
To read more about watchers, see the :ref:`Functions for watchers <box-watchers>` section.
712+
713+
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>`.
714+
715+
All registered watchers are automatically resubscribed when the connection is reestablished.
716+
717+
.. note::
718+
719+
Keep in mind that garbage collection of a watcher handle doesn't lead to the watcher's destruction.
720+
In this case, the watcher remains registered.
721+
It is okay to discard the result of ``watch`` function if the watcher will never be unregistered.
516722

517-
**Example:**
723+
**Examples:**
518724

519-
.. literalinclude:: /code_snippets/snippets/centralized_config/instances.enabled/tarantool_config_storage/myapp.lua
520-
:language: lua
521-
:start-at: config.storage.txn
522-
:end-at: })
523-
:dedent:
725+
.. literalinclude:: /code_snippets/snippets/centralized_config/instances.enabled/config_storage/myapp.lua
726+
:language: lua
727+
:start-after: function register_watchers
728+
:end-at: end)
729+
:dedent:
524730

525-
Example on GitHub: `tarantool_config_storage <https://github.com/tarantool/doc/tree/latest/doc/code_snippets/snippets/centralized_config/instances.enabled/tarantool_config_storage>`_
731+
Examples on GitHub: `config_storage <https://github.com/tarantool/doc/tree/latest/doc/code_snippets/snippets/centralized_config/instances.enabled/config_storage>`_
526732

527733
.. toctree::
528734
:maxdepth: 1

0 commit comments

Comments
 (0)
Please sign in to comment.