diff --git a/content/develop/clients/go/connect.md b/content/develop/clients/go/connect.md index a6e1f115e3..e7918f9087 100644 --- a/content/develop/clients/go/connect.md +++ b/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. | diff --git a/content/develop/clients/go/produsage.md b/content/develop/clients/go/produsage.md index 6d3ece994d..bb5a64a281 100644 --- a/content/develop/clients/go/produsage.md +++ b/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. diff --git a/content/develop/clients/lettuce/connect.md b/content/develop/clients/lettuce/connect.md index d610d36124..ec33031c11 100644 --- a/content/develop/clients/lettuce/connect.md +++ b/content/develop/clients/lettuce/connect.md @@ -254,3 +254,41 @@ 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) + .build(); + +redisClient.setOptions(clientOptions); + +try (StatefulRedisConnection connection = redisClient.connect()) { +// ... +// ... +``` diff --git a/content/develop/clients/lettuce/produsage.md b/content/develop/clients/lettuce/produsage.md index 1eb47d517d..d11e403410 100644 --- a/content/develop/clients/lettuce/produsage.md +++ b/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. diff --git a/content/develop/clients/nodejs/connect.md b/content/develop/clients/nodejs/connect.md index 80fc2433d5..843e87496a 100644 --- a/content/develop/clients/nodejs/connect.md +++ b/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 diff --git a/content/develop/clients/nodejs/produsage.md b/content/develop/clients/nodejs/produsage.md index 80403c982a..b7cbc5aec8 100644 --- a/content/develop/clients/nodejs/produsage.md +++ b/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. diff --git a/content/develop/clients/patterns/_index.md b/content/develop/clients/patterns/_index.md index d640b4ca70..ea1ec90d54 100644 --- a/content/develop/clients/patterns/_index.md +++ b/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. diff --git a/content/develop/clients/redis-py/connect.md b/content/develop/clients/redis-py/connect.md index 98767c6a3c..99f96c1527 100644 --- a/content/develop/clients/redis-py/connect.md +++ b/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. | diff --git a/content/develop/clients/redis-py/produsage.md b/content/develop/clients/redis-py/produsage.md index 4229852e87..ae63090a3d 100644 --- a/content/develop/clients/redis-py/produsage.md +++ b/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. diff --git a/content/develop/clients/sce.md b/content/develop/clients/sce.md new file mode 100644 index 0000000000..de2631134f --- /dev/null +++ b/content/develop/clients/sce.md @@ -0,0 +1,61 @@ +--- +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 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 "test@redis.com:test123" \ + -d '{ "client_maint_notifications": true }' \ + https://localhost:9443/v1/cluster +``` + +SCE 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 SCE. However, you can +configure some parameters, such as the timeouts to use +during maintenance. +See the pages linked below to learn how to configure 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" >}})