Updating docs related to retries and read_from_replicas.

Author: petyaslavova

docs/clustering.rst

@@ -187,8 +187,8 @@ When a ClusterPubSub instance is created without specifying a node, a
 single node will be transparently chosen for the pubsub connection on
 the first command execution. The node will be determined by: 1. Hashing
 the channel name in the request to find its keyslot 2. Selecting a node
-that handles the keyslot: If read_from_replicas is set to true, a
-replica can be selected.
+that handles the keyslot: If read_from_replicas is set to true or
+load_balancing_strategy is provided, a replica can be selected.
 
 Known PubSub Limitations
 ------------------------
@@ -216,9 +216,12 @@ By default, Redis Cluster always returns MOVE redirection response on
 accessing a replica node. You can overcome this limitation and scale
 read commands by triggering READONLY mode.
 
-To enable READONLY mode pass read_from_replicas=True to RedisCluster
-constructor. When set to true, read commands will be assigned between
+To enable READONLY mode pass read_from_replicas=True or define
+a load_balancing_strategy to RedisCluster constructor.
+When read_from_replicas is set to true read commands will be assigned between
 the primary and its replications in a Round-Robin manner.
+With load_balancing_strategy you can define a custom strategy for
+assigning read commands to the replicas and primary nodes.
 
 READONLY mode can be set at runtime by calling the readonly() method
 with target_nodes=‘replicas’, and read-write access can be restored by

docs/retry.rst

@@ -13,25 +13,25 @@ Retry in Redis Standalone
 >>> from redis.client import Redis
 >>> from redis.exceptions import (
 >>>    BusyLoadingError,
->>>    ConnectionError,
->>>    TimeoutError
+>>>    RedisError,
 >>> )
 >>>
 >>> # Run 3 retries with exponential backoff strategy
 >>> retry = Retry(ExponentialBackoff(), 3)
->>> # Redis client with retries on custom errors
->>> r = Redis(host='localhost', port=6379, retry=retry, retry_on_error=[BusyLoadingError, ConnectionError, TimeoutError])
->>> # Redis client with retries on TimeoutError only
->>> r_only_timeout = Redis(host='localhost', port=6379, retry=retry, retry_on_timeout=True)
+>>> # Redis client with retries on custom errors in addition to the errors
+>>> # that are already retried by default
+>>> r = Redis(host='localhost', port=6379, retry=retry, retry_on_error=[BusyLoadingError, RedisError])
 
-As you can see from the example above, Redis client supports 3 parameters to configure the retry behaviour:
+As you can see from the example above, Redis client supports 2 parameters to configure the retry behaviour:
 
 * ``retry``: :class:`~.Retry` instance with a :ref:`backoff-label` strategy and the max number of retries
-* ``retry_on_error``: list of :ref:`exceptions-label` to retry on
-* ``retry_on_timeout``: if ``True``, retry on :class:`~.TimeoutError` only
+    * The :class:`~.Retry` instance has default set of :ref:`exceptions-label` to retry on,
+      which can be overridden by passing a tuple with :ref:`exceptions-label` to the ``supported_errors`` parameter.
+* ``retry_on_error``: list of additional :ref:`exceptions-label` to retry on
 
-If either ``retry_on_error`` or ``retry_on_timeout`` are passed and no ``retry`` is given,
-by default it uses a ``Retry(NoBackoff(), 1)`` (meaning 1 retry right after the first failure).
+
+If no ``retry`` is provided, a default one is created with  :class:`~.ExponentialWithJitterBackoff` as backoff strategy
+and 3 retries.
 
 
 Retry in Redis Cluster
@@ -44,27 +44,36 @@ Retry in Redis Cluster
 >>> # Run 3 retries with exponential backoff strategy
 >>> retry = Retry(ExponentialBackoff(), 3)
 >>> # Redis Cluster client with retries
->>> rc = RedisCluster(host='localhost', port=6379, retry=retry, cluster_error_retry_attempts=2)
+>>> rc = RedisCluster(host='localhost', port=6379, retry=retry)
 
 Retry behaviour in Redis Cluster is a little bit different from Standalone:
 
-* ``retry``: :class:`~.Retry` instance with a :ref:`backoff-label` strategy and the max number of retries, default value is ``Retry(NoBackoff(), 0)``
-* ``cluster_error_retry_attempts``: number of times to retry before raising an error when :class:`~.TimeoutError` or :class:`~.ConnectionError` or :class:`~.ClusterDownError` are encountered, default value is ``3``
+* ``retry``: :class:`~.Retry` instance with a :ref:`backoff-label` strategy and the max number of retries, default value is ``Retry(ExponentialWithJitterBackoff(base=1, cap=10), cluster_error_retry_attempts)``
+* ``cluster_error_retry_attempts``: number of times to retry before raising an error when :class:`~.TimeoutError` or :class:`~.ConnectionError` or :class:`~.ClusterDownError` or :class:`~.SlotNotCoveredError` are encountered, default value is ``3``
+    * This argument is deprecated - it is used to initialize the number of retries for the retry object,
+      only in the case when the ``retry`` object is not provided.
+      When the ``retry`` argument is provided, the ``cluster_error_retry_attempts`` argument is ignored!
+
+* Starting from version 6.0.0 of the library, the default retry policy for the nodes connections is without retries.
+  This means that if a connection to a node fails, the lower level connection will not retry the connection.
+  Instead, it will raise a :class:`~.ConnectionError` to the cluster level call., where it will be retried.
+  This is done to avoid blocking the cluster client for too long in case of a node failure.
+
+* The retry object is not yet fully utilized in the cluster client.
+  The retry object is used only to determine the number of retries for the cluster level calls.
 
 Let's consider the following example:
 
 >>> from redis.backoff import ExponentialBackoff
 >>> from redis.retry import Retry
 >>> from redis.cluster import RedisCluster
 >>>
->>> rc = RedisCluster(host='localhost', port=6379, retry=Retry(ExponentialBackoff(), 6), cluster_error_retry_attempts=1)
+>>> rc = RedisCluster(host='localhost', port=6379, retry=Retry(ExponentialBackoff(), 6))
 >>> rc.set('foo', 'bar')
 
 #. the client library calculates the hash slot for key 'foo'.
 #. given the hash slot, it then determines which node to connect to, in order to execute the command.
 #. during the connection, a :class:`~.ConnectionError` is raised.
-#. because we set ``retry=Retry(ExponentialBackoff(), 6)``, the client tries to reconnect to the node up to 6 times, with an exponential backoff between each attempt.
-#. even after 6 retries, the client is still unable to connect.
-#. because we set ``cluster_error_retry_attempts=1``, before giving up, the client starts a cluster update, removes the failed node from the startup nodes, and re-initializes the cluster.
-#. after the cluster has been re-initialized, it starts a new cycle of retries, up to 6 retries, with an exponential backoff.
-#. if the client can connect, we're good. Otherwise, the exception is finally raised to the caller, because we've run out of attempts.
+#. because the default retry policy for the nodes connections is without retries, the error is raised to the cluster level call
+#. because we set ``retry=Retry(ExponentialBackoff(), 6)``, the cluster client starts a cluster update, removes the failed node from the startup nodes, and re-initializes the cluster.
+#. the cluster client retries the command until it either succeeds or the max number of retries is reached.

redis/asyncio/cluster.py

@@ -570,7 +570,9 @@ def get_retry(self) -> Retry:
 
     def set_retry(self, retry: Retry) -> None:
         if not isinstance(retry, Retry):
-            raise TypeError("retry must be a valid instance of redis.retry.Retry")
+            raise TypeError(
+                "retry must be a valid instance of redis.asyncio.retry.Retry"
+            )
         self.retry = retry
 
     def set_response_callback(self, command: str, callback: ResponseCallbackT) -> None: