Apply review suggestions

Author: xuniq

doc/platform/sharding/vshard_admin.rst

@@ -563,7 +563,7 @@ When such an operation is applied again, the value for the field increases by 2
 
 ..  note::
 
-    Any write requests that are intended to be executed repeatedly should be idempotent.
+    Any write requests that are intended to be executed repeatedly (for example, retried after an error) should be idempotent.
     The operations' idempotency ensures that the change is applied **only once**.
 
 A request may need to be run again if an error occurs on the server or client side.
@@ -588,17 +588,26 @@ In this case:
   Lack of such a check might lead to duplicate records or unplanned data changes.
 
   For example, a client has sent a request to the server. The client is waiting for a response within a specified timeout.
-  If the server sends a successful response after this time has elapsed, the client will receive an error.
+  If the server sends a successful response after this time has elapsed,
+  the client won't see this response due to a timeout, and will consider the request as failed.
   When re-executing this request without additional check, the operation may be applied twice.
 
-  A write request can be executed repeatedly without a check only if the error occurred on the server side --
-  for example, `ER_READONLY`.
+  A write request can be executed repeatedly without a check in two cases:
+  - The request is idempotent.
+  - It's known for sure that the previous request raised an error before executing any write operations.
+    For example, ER_READONLY was thrown by the server.
+    In this case, we know that the request couldn't complete due to server in read-only mode.
 
 **Deduplication examples**
 
 To ensure that the write requests (INSERT, UPDATE, UPSERT, and autoincrement) are idempotent,
 you should implement a check that the request is applied for the first time.
 
+..  note::
+
+    There is no built-in deduplication check in Tarantool.
+    Currently, deduplication can be only implemented by the user in the application code.
+
 For example, when you add a new tuple to a space, you can use a unique insert ID to check the request.
 In the example below within a single transaction:
 

doc/reference/reference_rock/vshard/vshard_router.rst

@@ -132,6 +132,15 @@ Router public API
         * ``timeout`` — a request timeout, in seconds. If the ``router`` cannot identify a
           shard with the specified ``bucket_id``, it will retry until the timeout is reached.
 
+        * ``request_timeout`` (since ``vshard`` 0.1.28) — timeout in seconds that serves as a protection against hung replicas.
+          The parameter is used in the read requests only (``mode=read``).
+          It is necessary to pass the ``request_timeout`` and ``timeout`` parameters together, with the following requirement:
+          ``timeout > request_timeout``.
+
+          The ``timeout`` parameter controls how much time a single request attempt may take.
+          When this time is over (the ``TimedOut`` error is raised), router retries the request on the next replica as long
+          as the ``timeout`` value is not elapsed.
+
         * other :ref:`net.box options <net_box-options>`, such as ``is_async``,
           ``buffer``, ``on_push`` are also supported.
 
@@ -163,12 +172,16 @@ Router public API
              optional attribute containing a message with the human-readable error description,
              and other attributes specific for the error code.
 
+    .. reference_vshard_note_start
+
     ..  note::
 
-        Any write requests that are intended to be executed repeatedly should be idempotent.
+        Any write requests that are intended to be executed repeatedly (for example, retried after an error) should be idempotent.
         The operations' idempotency ensures that the change is applied **only once**.
         Read more: :ref:`<vshard-deduplication>`.
 
+    .. reference_vshard_note_end
+
     **Examples:**
 
     To call ``customer_add`` function from ``vshard/example``, say:
@@ -205,6 +218,13 @@ Router public API
         * ``timeout`` — a request timeout, in seconds.If the ``router`` cannot identify a
           shard with the specified ``bucket_id``, it will retry until the timeout is reached.
 
+        * ``request_timeout`` (since ``vshard`` 0.1.28) — timeout in seconds that serves as a protection against hung replicas.
+          It is necessary to pass the ``request_timeout`` and ``timeout`` parameters together, with the following requirement:
+          ``timeout > request_timeout``.
+          The ``timeout`` parameter controls how much time a single request attempt may take.
+          When this time is over (the ``TimedOut`` error is raised), router retries the request on the next replica as long
+          as the ``timeout`` value is not elapsed.
+
         * other :ref:`net.box options <net_box-options>`, such as ``is_async``,
           ``buffer``, ``on_push`` are also supported.
 
@@ -254,6 +274,10 @@ Router public API
     optional attribute containing a message with the human-readable error description,
     and other attributes specific for this error code.
 
+    ..  include:: /reference/reference_rock/vshard/vshard_router.rst
+        :start-after: reference_vshard_note_start
+        :end-before: reference_vshard_note_end
+
 ..  _router_api-callre:
 
 ..  function:: vshard.router.callre(bucket_id, function_name, {argument_list}, {options})
@@ -273,6 +297,13 @@ Router public API
         * ``timeout`` — a request timeout, in seconds. If the ``router`` cannot identify a
           shard with the specified ``bucket_id``, it will retry until the timeout is reached.
 
+        * ``request_timeout`` (since ``vshard`` 0.1.28) — timeout in seconds that serves as a protection against hung replicas.
+          It is necessary to pass the ``request_timeout`` and ``timeout`` parameters together, with the following requirement:
+          ``timeout > request_timeout``.
+          The ``timeout`` parameter controls how much time a single request attempt may take.
+          When this time is over (the ``TimedOut`` error is raised), router retries the request on the next replica as long
+          as the ``timeout`` value is not elapsed.
+
         * other :ref:`net.box options <net_box-options>`, such as ``is_async``,
           ``buffer``, ``on_push`` are also supported.