draft

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,11 +588,15 @@ 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 errored 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**
 

doc/reference/reference_rock/vshard/vshard_router.rst

@@ -132,6 +132,8 @@ 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``  — timeout in seconds
+
         * other :ref:`net.box options <net_box-options>`, such as ``is_async``,
           ``buffer``, ``on_push`` are also supported.
 
@@ -163,12 +165,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:
@@ -254,6 +260,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})