[5pt] vshard.storage.enable/disable()

[TarantoolBot]

Product: Tarantool, vshard
Root document: https://www.tarantool.io/en/doc/latest/reference/reference_rock/vshard/vshard_api/
SME: @ Gerold103

Seems the description of the vshard.storage.disable()/enable() functions is missing in the reference. Need to add sections for those functions including the info below in Details.

Details

vshard.storage.disable() makes most of the vshard.storage
functions throw an error. As Lua exception, not via nil, err
pattern.

vshard.storage.enable() reverts the disable.

By default the storage is enabled.

Additionally, the storage is forcefully disabled automatically
until vshard.storage.cfg() is finished and the instance finished
recovery (its box.info.status is 'running', for example).

Auto-disable protects from usage of vshard functions before the
storage's global state is fully created.

Manual vshard.storage.disable() helps to achieve the same for
user's application. For instance, a user might want to do some
preparatory work after vshard.storage.cfg before the application
is ready for requests. Then the flow would be:

vshard.storage.disable()
vshard.storage.cfg(...)
-- Do your preparatory work here ...
vshard.storage.enable()

The routers handle the errors signaling about the storage being disabled in a
special way. They put connections to such instances into a backoff state for
some time and will try to use other replicas. For example, assume a replicaset
has replicas 'replica_1' and 'replica_2'. Assume 'replica_1' is disabled due to
any reason. If a router will try to talk to 'replica_1', it will get a special
error and will transparently retry to 'replica_2'.

When 'replica_1' is enabled again, the router will notice it too and will send
requests to it again.

It all works exclusively for read-only requests. Read-write requests can only be
sent to a master, which is one per replicaset. They are not retried.
Requested by @Gerold103 in tarantool/vshard@2eb17c4.

More info: tarantool/vshard@5d935fc