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

content/develop/clients/go/connect.md

@@ -126,3 +126,39 @@ if err != nil {
 }
 fmt.Println("foo", val)
 ```
+
+## Connect using Seamless client experience (SCE)
+
+*Seamless client experience (SCE)* 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 [Seamless client experience]({{< relref "/develop/clients/sce" >}})
+for more information about SCE.
+
+To enable SCE on the client, add the `HitlessUpgrades` option during the
+connection, as shown in the following example:
+
+```go
+rdb := redis.NewClient(&redis.Options{
+    Addr:     "localhost:6379",
+    Protocol: 3, // RESP3 required
+    HitlessUpgrades: &hitless.Config{
+        Mode:               hitless.MaintNotificationsEnabled,
+        RelaxedTimeout:     10 * time.Second,
+    },
+})
+```
+
+{{< note >}}SCE requires the [RESP3]({{< relref "/develop/reference/protocol-spec#resp-versions" >}})
+protocol, so you must set `Protocol:3` explicitly when you connect.
+{{< /note >}}
+
+The `hitless.Config` object accepts the following parameters:
+
+| Name | Description |
+|------ |------------- |
+| `Mode` | Whether or not to enable SCE. The options are `hitless.MaintNotificationsDisabled`, `hitless.MaintNotificationsEnabled` (require SCE and abort the connection if not supported), and `hitless.MaintNotificationsAuto` (require SCE and fall back to a non-SCE connection if not supported). The default is `hitless.MaintNotificationsAuto`.   |
+| `RelaxedTimeout` | The timeout to use for commands and connections while the server is performing maintenance. The default is 10 seconds. |
+| `HandoffTimeout` | The timeout to connect to the replacement node. The default is 15 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" >}}Seamless client experience{{< /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.
+
+### Seamless client experience
+
+*Seamless client experience (SCE)* 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 [Seamless client experience]({{< relref "/develop/clients/sce" >}})
+for more information about SCE and
+[Connect using Seamless client experience]({{< relref "/develop/clients/go/connect#connect-using-seamless-client-experience-sce" >}})
+for example code.

content/develop/clients/lettuce/connect.md

@@ -254,3 +254,47 @@ 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 Seamless client experience (SCE)
+
+*Seamless client experience (SCE)* 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 [Seamless client experience]({{< relref "/develop/clients/sce" >}})
+for more information about SCE.
+
+To enable SCE on the client, create a `MaintenanceEventsOptions` object
+and pass it to the `ClientOptions` builder using the `supportMaintenanceEvents()` method:
+
+```java
+import io.lettuce.core.*;
+import io.lettuce.core.api.StatefulRedisConnection;
+import io.lettuce.core.protocol.ProtocolVersion;
+  .
+  .
+
+RedisClient redisClient = RedisClient.create("redis://localhost:6379");
+
+MaintenanceEventsOptions maintOptions = MaintenanceEventsOptions.builder()
+    // You can also pass `false` as a parameter to `supportMaintenanceEvents()`
+    // to explicitly disable SCE.
+    .supportMaintenanceEvents()
+    .build();
+
+ClientOptions clientOptions = ClientOptions.builder()
+    .supportMaintenanceEvents(maintOptions)
+    .protocolVersion(ProtocolVersion.RESP3)
+    .build();
+
+redisClient.setOptions(clientOptions);
+
+try (StatefulRedisConnection<String, String> connection = redisClient.connect()) {
+  .
+  .
+```
+
+{{< note >}}SCE requires the [RESP3]({{< relref "/develop/reference/protocol-spec#resp-versions" >}})
+protocol, so you must add the option `protocolVersion(ProtocolVersion.RESP3)`
+to the `ClientOptions` builder explicitly.
+{{< /note >}}

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" >}}Seamless client experience{{< /checklist-item >}}
 {{< /checklist >}}
 
 ## Recommendations
@@ -238,3 +239,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.
+
+## Seamless client experience
+
+*Seamless client experience (SCE)* 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 [Seamless client experience]({{< relref "/develop/clients/sce" >}})
+for more information about SCE and
+[Connect using Seamless client experience]({{< relref "/develop/clients/lettuce/connect#connect-using-seamless-client-experience-sce" >}})
+for example code.

content/develop/clients/nodejs/connect.md

@@ -329,6 +329,44 @@ createClient({
 });
 ```
 
+## Connect using Seamless client experience (SCE)
+
+*Seamless client experience (SCE)* 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 [Seamless client experience]({{< relref "/develop/clients/sce" >}})
+for more information about SCE.
+
+Use the configuration options shown in the example below to enable SCE
+during the connection:
+
+```js
+const client = createClient({
+  RESP: 3,
+  maintPushNotifications: 'auto',
+  maintRelaxedCommandTimeout: 10000,
+  maintRelaxedSocketTimeout: 10000,
+  ...
+});
+```
+
+{{< note >}}SCE 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:
+
+-   `maintPushNotifications`: (`string`) Whether or not to enable SCE. The options are  
+    -   `'disabled'`: don't use SCE
+    -   `'enabled'`: attempt to activate SCE on the server and abort the connection if it isn't supported
+    -   `'auto'`: attempt to activate SCE on the server and fall back to a non-SCE
+        connection if it isn't supported. 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" >}}Seamless client experience{{< /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.
+
+### Seamless client experience
+
+*Seamless client experience (SCE)* 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 [Seamless client experience]({{< relref "/develop/clients/sce" >}})
+for more information about SCE and
+[Connect using Seamless client experience]({{< relref "/develop/clients/nodejs/connect#connect-using-seamless-client-experience-sce" >}})
+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,44 @@ 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 Seamless client experience (SCE)
+
+*Seamless client experience (SCE)* 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 [Seamless client experience]({{< relref "/develop/clients/sce" >}})
+for more information about SCE.
+
+To enable SCE on the client, pass a `MaintenanceEventsConfig` object
+during the connection, as shown in the following example:
+
+```py
+import redis
+from redis.connection import MaintenanceEventsConfig
+from redis.maintenance_events import EndpointType
+
+r = redis.Redis(
+    decode_responses=True,
+    protocol=3,
+    maintenance_events_config = MaintenanceEventsConfig(
+        enabled=True,
+        proactive_reconnect=True,
+        relax_timeout=10,
+    ),
+    ...
+)
+```
+
+{{< note >}}SCE requires the [RESP3]({{< relref "/develop/reference/protocol-spec#resp-versions" >}})
+protocol, so you must set `protocol=3` explicitly when you connect.
+{{< /note >}}
+
+The `MaintenanceEventsConfig` constructor accepts the following parameters:
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `enabled` | `bool` | `False` | Whether or not to enable SCE. |
+| `proactive_reconnect` | `bool` | `True` | Whether or not to automatically reconnect when a node is replaced. |
+| `relax_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" >}}Seamless client experience{{< /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.
+
+### Seamless client experience
+
+*Seamless client experience (SCE)* 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 [Seamless client experience]({{< relref "/develop/clients/sce" >}})
+for more information about SCE and
+[Connect using Seamless client experience]({{< relref "/develop/clients/redis-py/connect#connect-using-seamless-client-experience-sce" >}})
+for example code.

content/develop/clients/sce.md

@@ -0,0 +1,45 @@
+---
+categories:
+- docs
+- develop
+- stack
+- oss
+- rs
+- rc
+- oss
+- kubernetes
+- clients
+description: Learn how to avoid disruptions during Redis server maintenance.
+linkTitle: Seamless client experience
+title: Seamless client experience
+weight: 50
+---
+
+*Seamless client experience (SCE)* 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.
+
+SCE is primarily useful when server software or hardware is upgraded.
+Upgrades tend to impact the general performance of the server, so
+advance notification of the upgrade lets a client adjust its command
+timeouts to take this into account. 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 SCE
+
+SCE is enabled by default on Redis Cloud, but you must enable it
+explicitly on Redis Enterprise servers.
+
+You must also configure SCE on the client side during connection.
+See the pages linked below to learn how to enable SCE for:
+
+- [redis-py]({{< relref "/develop/clients/redis-py/connect#connect-using-seamless-client-experience-sce" >}})
+- [node-redis]({{< relref "/develop/clients/nodejs/connect#connect-using-seamless-client-experience-sce" >}})
+- [Lettuce]({{< relref "/develop/clients/lettuce/connect#connect-using-seamless-client-experience-sce" >}})
+- [go-redis]({{< relref "/develop/clients/go/connect#connect-using-seamless-client-experience-sce" >}})