Merge pull request #2120 from redis/DOC-5712-python-seamless-section

DOC-5711 DOC-5712 DOC-5713 DOC-5714 DOC-5716 Smart client handoffs docs

Author: andy-stark-redis

content/develop/clients/go/connect.md

@@ -126,3 +126,45 @@ if err != nil {
 }
 fmt.Println("foo", val)
 ```
+
+## Connect using Smart client handoffs (SCH)
+
+*Smart client handoffs (SCH)* is a feature of Redis Cloud and
+Redis Enterprise servers that lets them actively notify clients
+about planned server maintenance shortly before it happens. This
+lets a client take action to avoid disruptions in service.
+See [Smart client handoffs]({{< relref "/develop/clients/sch" >}})
+for more information about SCH.
+
+To enable SCH on the client, add the `MaintNotificationsConfig` option during the
+connection, as shown in the following example:
+
+```go
+rdb := redis.NewClient(&redis.Options{
+    Addr:     "localhost:6379",
+    Protocol: 3, // RESP3 required
+    MaintNotificationsConfig: &maintnotifications.Config{
+            Mode:                       maintnotifications.ModeEnabled,
+            EndpointType:               maintnotifications.EndpointTypeExternalIP,
+            HandoffTimeout:             10 * time.Second,
+            RelaxedTimeout:             10 * time.Second,
+            PostHandoffRelaxedDuration: 10 * time.Second,
+            MaxHandoffRetries:          5,
+    },
+})
+```
+
+{{< note >}}SCH requires the [RESP3]({{< relref "/develop/reference/protocol-spec#resp-versions" >}})
+protocol, so you must set `Protocol:3` explicitly when you connect.
+{{< /note >}}
+
+The `maintnotifications.Config` object accepts the following parameters:
+
+| Name | Description |
+|------ |------------- |
+| `Mode` | Whether or not to enable SCH. The options are `ModeDisabled`, `ModeEnabled` (require SCH and abort the connection if not supported), and `ModeAuto` (require SCH and fall back to a non-SCH connection if not supported). The default is `ModeAuto`.   |
+| `EndpointType` | The type of endpoint to use for the connection. The options are `EndpointTypeExternalIP`, `EndpointTypeInternalIP`, `EndpointTypeExternalFQDN`, `EndpointTypeInternalFQDN`, `EndpointTypeAuto` (auto-detect based on connection), and `EndpointTypeNone` (reconnect with current config). The default is `EndpointTypeExternalIP`. |
+| `HandoffTimeout` | The timeout to connect to the replacement node. The default is 15 seconds. |
+| `RelaxedTimeout` | The timeout to use for commands and connections while the server is performing maintenance. The default is 10 seconds. |
+| `PostHandoffRelaxedDuration` | The duration to continue using relaxed timeouts after a successful handoff (this provides extra resilience during cluster transitions). The default is 20 seconds. |
+| `MaxHandoffRetries` | The maximum number of times to retry connecting to the replacement node. The default is 3. |

content/develop/clients/go/produsage.md

@@ -30,6 +30,7 @@ progress in implementing the recommendations.
     {{< checklist-item "#monitor-performance-and-errors">}}Monitor performance and errors{{< /checklist-item >}}
     {{< checklist-item "#retries" >}}Retries{{< /checklist-item >}}
     {{< checklist-item "#timeouts" >}}Timeouts{{< /checklist-item >}}
+    {{< checklist-item "#seamless-client-experience" >}}Smart client handoffs{{< /checklist-item >}}
 {{< /checklist >}}
 
 ## Recommendations
@@ -122,3 +123,15 @@ for your application. If timeouts are set too short, then `go-redis`
 might retry commands that would have succeeded if given more time. However,
 if they are too long, your app might hang unnecessarily while waiting for a
 response that will never arrive.
+
+### Smart client handoffs
+
+*Smart client handoffs (SCH)* is a feature of Redis Cloud and
+Redis Enterprise servers that lets them actively notify clients
+about planned server maintenance shortly before it happens. This
+lets a client take action to avoid disruptions in service.
+
+See [Smart client handoffs]({{< relref "/develop/clients/sch" >}})
+for more information about SCH and
+[Connect using Smart client handoffs]({{< relref "/develop/clients/go/connect#connect-using-smart-client-handoffs-sch" >}})
+for example code.

content/develop/clients/lettuce/connect.md

@@ -254,3 +254,74 @@ public class Pool {
 ```
 
 In this setup, `LettuceConnectionFactory` is a custom class you would need to implement, adhering to Apache Commons Pool's `PooledObjectFactory` interface, to manage lifecycle events of pooled `StatefulRedisConnection` objects.
+
+## Connect using Smart client handoffs (SCH)
+
+*Smart client handoffs (SCH)* is a feature of Redis Cloud and
+Redis Enterprise servers that lets them actively notify clients
+about planned server maintenance shortly before it happens. This
+lets a client take action to avoid disruptions in service.
+See [Smart client handoffs]({{< relref "/develop/clients/sch" >}})
+for more information about SCH.
+
+To enable SCH on the client, create a `MaintNotificationsConfig` object
+and/or a `TimeoutOptions` object
+and pass them to the `ClientOptions` builder as shown in the example below:
+
+```java
+import io.lettuce.core.*;
+import io.lettuce.core.api.StatefulRedisConnection;
+import io.lettuce.core.protocol.ProtocolVersion;
+import java.time.Duration;
+//  ...
+//  ...
+
+RedisClient redisClient = RedisClient.create("redis://localhost:6379");
+
+MaintNotificationsConfig maintNotificationsConfig = MaintNotificationsConfig.builder()
+        .enableMaintNotifications()
+        // .autoResolveEndpointType() // default is auto-resolve
+        .endpointType(EndpointType.INTERNAL_IP)
+        .build();
+
+TimeoutOptions timeoutOptions = TimeoutOptions.builder()
+        .relaxedTimeoutsDuringMaintenance(Duration.ofSeconds(10))
+        .build();
+
+ClientOptions clientOptions = ClientOptions.builder()
+        .maintNotificationsConfig(maintNotificationsConfig)
+        .timeoutOptions(timeoutOptions)
+        .build();
+
+redisClient.setOptions(clientOptions);
+
+// or
+ClientOptions clientOptions = ClientOptions.builder()
+        .maintNotificationsConfig(MaintNotificationsConfig.enabled(EndpointType.INTERNAL_IP))
+        .build();
+
+redisClient.setOptions(clientOptions);
+
+// or
+ClientOptions clientOptions = ClientOptions.builder()
+        .maintNotificationsConfig(MaintNotificationsConfig.enabled())
+        .build();
+
+redisClient.setOptions(clientOptions);
+```
+
+The `MaintNotificationsConfig` builder accepts the following options:
+
+| Method | Description |
+|--------|-------------|
+| `enableMaintNotifications()` | Enable SCH. |
+| `endpointType(EndpointType type)` | Set the type of endpoint to use for the connection. The options are `EndpointType.EXTERNAL_IP`, `EndpointType.INTERNAL_IP`, `EndpointType.EXTERNAL_FQDN`, `EndpointType.INTERNAL_FQDN`, and `EndpointType.NONE`. Use the separate `autoResolveEndpointType()` method to auto-detect based on the connection (this is the default behavior). |
+| `autoResolveEndpointType()` | Auto-detect the type of endpoint to use for the connection. This is the default behavior. Use `endpointType()` to set a specific endpoint type. |
+
+Among other options, the `TimeoutOptions` builder accepts the following option
+that is relevant to SCH:
+
+| Method | Description |
+|--------|-------------|
+| `relaxedTimeoutsDuringMaintenance(Duration duration)` | Set the timeout to use while the server is performing maintenance. The default is 10 seconds. |
+|

content/develop/clients/lettuce/produsage.md

@@ -30,6 +30,7 @@ progress in implementing the recommendations.
     {{< checklist-item "#dns-cache-and-redis" >}}DNS cache and Redis{{< /checklist-item >}}
     {{< checklist-item "#exception-handling" >}}Exception handling{{< /checklist-item >}}
     {{< checklist-item "#connection-and-execution-reliability" >}}Connection and execution reliability{{< /checklist-item >}}
+    {{< checklist-item "#seamless-client-experience" >}}Smart client handoffs{{< /checklist-item >}}
 {{< /checklist >}}
 
 ## Recommendations
@@ -283,3 +284,15 @@ client.setOptions(ClientOptions.builder()
 See
 [Command execution reliability](https://redis.github.io/lettuce/advanced-usage/#command-execution-reliability)
 in the Lettuce reference guide for more information.
+
+## Smart client handoffs
+
+*Smart client handoffs (SCH)* is a feature of Redis Cloud and
+Redis Enterprise servers that lets them actively notify clients
+about planned server maintenance shortly before it happens. This
+lets a client take action to avoid disruptions in service.
+
+See [Smart client handoffs]({{< relref "/develop/clients/sch" >}})
+for more information about SCH and
+[Connect using Smart client handoffs]({{< relref "/develop/clients/lettuce/connect#connect-using-smart-client-handoffs-sch" >}})
+for example code.

content/develop/clients/nodejs/connect.md

@@ -329,6 +329,51 @@ createClient({
 });
 ```
 
+## Connect using Smart client handoffs (SCH)
+
+*Smart client handoffs (SCH)* is a feature of Redis Cloud and
+Redis Enterprise servers that lets them actively notify clients
+about planned server maintenance shortly before it happens. This
+lets a client take action to avoid disruptions in service.
+See [Smart client handoffs]({{< relref "/develop/clients/sch" >}})
+for more information about SCH.
+
+Use the configuration options shown in the example below to enable SCH
+during the connection:
+
+```js
+const client = createClient({
+  RESP: 3,
+  maintNotifications: 'auto',
+  maintEndpointType: 'auto',
+  maintRelaxedCommandTimeout: 10000,
+  maintRelaxedSocketTimeout: 10000,
+  ...
+});
+```
+
+{{< note >}}SCH requires the [RESP3]({{< relref "/develop/reference/protocol-spec#resp-versions" >}})
+protocol, so you must set the `RESP:3` option explicitly when you connect.
+{{< /note >}}
+
+The available options are:
+
+-   `maintNotifications`: (`string`) Whether or not to enable SCH. The options are  
+    -   `'disabled'`: don't use SCH
+    -   `'enabled'`: attempt to activate SCH on the server and abort the connection if it isn't supported
+    -   `'auto'`: attempt to activate SCH on the server and fall back to a non-SCH
+        connection if it isn't supported. This is the default.
+-   `maintEndpointType`: (`MovingEndpointType`) The type of endpoint to use for the connection. The options are:
+    -   `'external-ip'`: use the external IP address of the server
+    -   `'internal-ip'`: use the internal IP address of the server
+    -   `'external-fqdn'`: use the external FQDN of the server
+    -   `'internal-fqdn'`: use the internal FQDN of the server
+    -   `'auto'`: auto-detect based on connection. This is the default.
+-   `maintRelaxedCommandTimeout`: (`number`) The command timeout to use while the server is 
+    performing maintenance. The default is 10000 (10 seconds). If a timeout happens during the maintenance period, the client receives a `CommandTimeoutDuringMaintenance` error.
+-   `maintRelaxedSocketTimeout`: (`number`) The socket timeout to use while the server is 
+    performing maintenance. The default is 10000 (10 seconds). If a timeout happens during the maintenance period, the client receives a `SocketTimeoutDuringMaintenance` error.
+
 ## Connection events
 
 The client object emits the following

content/develop/clients/nodejs/produsage.md

@@ -29,6 +29,7 @@ progress in implementing the recommendations.
     {{< checklist-item "#handling-reconnections" >}}Handling reconnections{{< /checklist-item >}}
     {{< checklist-item "#connection-timeouts" >}}Connection timeouts{{< /checklist-item >}}
     {{< checklist-item "#command-execution-reliability" >}}Command execution reliability{{< /checklist-item >}}
+    {{< checklist-item "#seamless-client-experience" >}}Smart client handoffs{{< /checklist-item >}}
 {{< /checklist >}}
 
 ## Recommendations
@@ -105,3 +106,15 @@ const client = createClient({
 
 Use a separate connection with the queue disabled if you want to avoid queuing
 only for specific commands.
+
+### Smart client handoffs
+
+*Smart client handoffs (SCH)* is a feature of Redis Cloud and
+Redis Enterprise servers that lets them actively notify clients
+about planned server maintenance shortly before it happens. This
+lets a client take action to avoid disruptions in service.
+
+See [Smart client handoffs]({{< relref "/develop/clients/sch" >}})
+for more information about SCH and
+[Connect using Smart client handoffs]({{< relref "/develop/clients/nodejs/connect#connect-using-smart-client-handoffs-sch" >}})
+for example code.

content/develop/clients/patterns/_index.md

@@ -13,7 +13,7 @@ description: Novel patterns for working with Redis data structures
 linkTitle: Coding patterns
 title: Coding patterns
 aliases: /develop/use/patterns
-weight: 50
+weight: 60
 ---
 
 The following documents describe some novel development patterns you can use with Redis.

content/develop/clients/redis-py/connect.md

@@ -252,3 +252,45 @@ a simple retry strategy by default, but there are various ways you can customize
 this behavior to suit your use case. See
 [Retries]({{< relref "/develop/clients/redis-py/produsage#retries" >}})
 for more information about custom retry strategies, with example code.
+
+## Connect using Smart client handoffs (SCH)
+
+*Smart client handoffs (SCH)* is a feature of Redis Cloud and
+Redis Enterprise servers that lets them actively notify clients
+about planned server maintenance shortly before it happens. This
+lets a client take action to avoid disruptions in service.
+See [Smart client handoffs]({{< relref "/develop/clients/sch" >}})
+for more information about SCH.
+
+To enable SCH on the client, pass a `MaintNotificationsConfig` object
+during the connection, as shown in the following example:
+
+```py
+import redis
+from redis.maint_notifications import MaintNotificationsConfig, EndpointType
+
+r = redis.Redis(
+    decode_responses=True,
+    protocol=3,
+    maint_notifications_config=MaintNotificationsConfig(
+        enabled=True,
+        proactive_reconnect=True,
+        relaxed_timeout=10,
+        endpoint_type=EndpointType.EXTERNAL_IP
+    ),
+    ...
+)
+```
+
+{{< note >}}SCH requires the [RESP3]({{< relref "/develop/reference/protocol-spec#resp-versions" >}})
+protocol, so you must set `protocol=3` explicitly when you connect.
+{{< /note >}}
+
+The `MaintNotificationsConfig` constructor accepts the following parameters:
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `enabled` | `bool` | `False` | Whether or not to enable SCH. |
+| `proactive_reconnect` | `bool` | `True` | Whether or not to automatically reconnect when a node is replaced. |
+| `endpoint_type` | `EndpointType` | Auto-detect | The type of endpoint to use for the connection. The options are `EndpointType.EXTERNAL_IP`, `EndpointType.INTERNAL_IP`, `EndpointType.EXTERNAL_FQDN`, `EndpointType.INTERNAL_FQDN`, and `EndpointType.NONE`. |
+| `relaxed_timeout` | `int` | `20` | The timeout (in seconds) to use while the server is performing maintenance. A value of `-1` disables the relax timeout and just uses the normal timeout during maintenance. |

content/develop/clients/redis-py/produsage.md

@@ -30,6 +30,7 @@ progress in implementing the recommendations.
     {{< checklist-item "#health-checks" >}}Health checks{{< /checklist-item >}}
     {{< checklist-item "#exception-handling" >}}Exception handling{{< /checklist-item >}}
     {{< checklist-item "#timeouts" >}}Timeouts{{< /checklist-item >}}
+    {{< checklist-item "#seamless-client-experience" >}}Smart client handoffs{{< /checklist-item >}}
 {{< /checklist >}}
 
 ## Recommendations
@@ -197,3 +198,15 @@ If you use timeouts that are too short, then `redis-py` might retry
 commands that would have succeeded if given more time. However, if the
 timeouts are too long, your app might hang unnecessarily while waiting for a
 response that will never arrive.
+
+### Smart client handoffs
+
+*Smart client handoffs (SCH)* is a feature of Redis Cloud and
+Redis Enterprise servers that lets them actively notify clients
+about planned server maintenance shortly before it happens. This
+lets a client take action to avoid disruptions in service.
+
+See [Smart client handoffs]({{< relref "/develop/clients/sch" >}})
+for more information about SCH and
+[Connect using Smart client handoffs]({{< relref "/develop/clients/redis-py/connect#connect-using-smart-client-handoffs-sch" >}})
+for example code.

content/develop/clients/sch.md

@@ -0,0 +1,65 @@
+---
+categories:
+- docs
+- develop
+- stack
+- oss
+- rs
+- rc
+- oss
+- kubernetes
+- clients
+description: Learn how to avoid disruptions during Redis server maintenance.
+linkTitle: Smart client handoffs
+title: Smart client handoffs
+weight: 50
+---
+
+*Smart client handoffs (SCH)* is a feature of Redis Cloud and
+Redis Enterprise servers that lets them actively notify clients
+about planned server maintenance shortly before it happens. This
+lets a client reconnect or otherwise respond gracefully without significant
+interruptions in service.
+
+SCH is primarily useful when server software or hardware upgrades
+are required. It provides two main features to help the
+client avoid disruptions in service during the maintenance period:
+
+-   **Relaxed timeouts**: Upgrades tend to impact the general performance of the server.
+    Advance notification of the upgrade lets a client adjust its command
+    timeouts to take this into account and avoid aborting commands too soon.
+-   **Transparent reconnection**: Upgrades also involve migrating
+    Redis shards to new nodes, which inevitably disconnects clients from
+    existing nodes. However, with some advance warning of the disconnection,
+    a client can buffer commands, connect to a new node, and then resume
+    the buffered commands without aborting any of them. As a result, users
+    see no disruption in service.
+
+## Enable SCH
+
+SCH is enabled by default on Redis Cloud, but you must enable it
+explicitly on Redis Enterprise servers by using the
+[v1/cluster]({{< relref "/operate/rs/references/rest-api/requests/cluster" >}})
+REST API request to set the `client_maint_notifications` option to `true`.
+The example below shows how to do this using the
+[`curl`](https://curl.se/) command line utility:
+
+```bash
+curl -k -X PUT -H "accept: application/json" \
+    -H "content-type: application/json" \
+    -u "[email protected]:test123" \
+    -d '{ "client_maint_notifications": true }' \
+    https://localhost:9443/v1/cluster
+```
+
+SCH is enabled automatically on the client side during connection
+if you select the [RESP3]({{< relref "/develop/reference/protocol-spec#resp-versions" >}})
+protocol, which is a requirement for SCH. However, you can
+configure some parameters, such as the timeouts to use
+during maintenance.
+See the pages linked below to learn how to configure SCH for:
+
+- [redis-py]({{< relref "/develop/clients/redis-py/connect#connect-using-smart-client-handoffs-sch" >}})
+- [node-redis]({{< relref "/develop/clients/nodejs/connect#connect-using-smart-client-handoffs-sch" >}})
+- [Lettuce]({{< relref "/develop/clients/lettuce/connect#connect-using-smart-client-handoffs-sch" >}})
+- [go-redis]({{< relref "/develop/clients/go/connect#connect-using-smart-client-handoffs-sch" >}})