Support 8.4 CAS/CAD (IF*) operations (#2978)

* Completely untested start for CAD/CAD

* unit tests

* propose the actual API

* DIGEST integration tests

* compensate for leading-zero oddness

* apply fixes for server hash format changes

* use CAS/CAD in locking operations

* release notes

* remove mitigations for receiving under-length digests from the server (now fixed at server)

* add zero-length digest test

* Update src/StackExchange.Redis/Interfaces/IDatabaseAsync.cs

Co-authored-by: Philo <[email protected]>

---------

Co-authored-by: Philo <[email protected]>

Author: mgravell

Directory.Packages.props

@@ -8,6 +8,7 @@
     <PackageVersion Include="System.Threading.Channels" Version="5.0.0" />
     <PackageVersion Include="System.Runtime.InteropServices.RuntimeInformation" Version="4.3.0" />
     <PackageVersion Include="System.IO.Compression" Version="4.3.0" />
+    <PackageVersion Include="System.IO.Hashing" Version="9.0.10" />
 
     <!-- For analyzers, tied to the consumer's build SDK; at the moment, that means "us" -->
     <PackageVersion Include="Microsoft.CodeAnalysis.CSharp" Version="4.12.0" />

docs/ReleaseNotes.md

@@ -8,6 +8,8 @@ Current package versions:
 
 ## Unreleased
 
+- Support Redis 8.4 CAS/CAD operations (`DIGEST`, and the `IFEQ`, `IFNE`, `IFDEQ`, `IFDNE` modifiers on `SET` / `DEL`)
+  via the new `ValueCondition` abstraction, and use CAS/CAD operations for `Lock*` APIs when possible ([#2978 by mgravell](https://github.com/StackExchange/StackExchange.Redis/pull/2978))
 - Support `XREADGROUP CLAIM` ([#2972 by mgravell](https://github.com/StackExchange/StackExchange.Redis/pull/2972)) 
 - Support `MSETEX` (Redis 8.4.0) for multi-key operations with expiration ([#2977 by mgravell](https://github.com/StackExchange/StackExchange.Redis/pull/2977))
 

docs/exp/SER002.md

@@ -2,15 +2,15 @@ Redis 8.4 is currently in preview and may be subject to change.
 
 New features in Redis 8.4 include:
 
-- [`MSETEX`](https://github.com/redis/redis/pull/14434) for setting multiple strings with expiry
+- [`MSETEX`](https://github.com/redis/redis/pull/14434) for setting multiple strings with expiry 
 - [`XREADGROUP ... CLAIM`](https://github.com/redis/redis/pull/14402) for simplifed stream consumption
 - [`SET ... {IFEQ|IFNE|IFDEQ|IFDNE}`, `DELEX` and `DIGEST`](https://github.com/redis/redis/pull/14434) for checked (CAS/CAD) string operations
 
 The corresponding library feature must also be considered subject to change:
 
 1. Existing bindings may cease working correctly if the underlying server API changes.
 2. Changes to the server API may require changes to the library API, manifesting in either/both of build-time
-   or run-time breaks.
+   or run-time breaks. 
 
 While this seems *unlikely*, it must be considered a possibility. If you acknowledge this, you can suppress
 this warning by adding the following to your `csproj` file:

src/Directory.Build.props

@@ -4,6 +4,7 @@
     <GenerateDocumentationFile>true</GenerateDocumentationFile>
     <IsPackable>true</IsPackable>
     <CheckEolTargetFramework>false</CheckEolTargetFramework>
+    <SuppressTfmSupportBuildWarnings>true</SuppressTfmSupportBuildWarnings>
   </PropertyGroup>
   <ItemGroup>
     <PackageReference Include="Microsoft.CodeAnalysis.PublicApiAnalyzers" PrivateAssets="all" />

src/StackExchange.Redis/Enums/RedisCommand.cs

@@ -30,6 +30,8 @@ internal enum RedisCommand
     DECR,
     DECRBY,
     DEL,
+    DELEX,
+    DIGEST,
     DISCARD,
     DUMP,
 
@@ -300,6 +302,8 @@ internal static bool IsPrimaryOnly(this RedisCommand command)
             case RedisCommand.DECR:
             case RedisCommand.DECRBY:
             case RedisCommand.DEL:
+            case RedisCommand.DELEX:
+            case RedisCommand.DIGEST:
             case RedisCommand.EXPIRE:
             case RedisCommand.EXPIREAT:
             case RedisCommand.FLUSHALL:

src/StackExchange.Redis/Experiments.cs

@@ -8,6 +8,7 @@ namespace StackExchange.Redis
     internal static class Experiments
     {
         public const string UrlFormat = "https://stackexchange.github.io/StackExchange.Redis/exp/";
+
         public const string VectorSets = "SER001";
         // ReSharper disable once InconsistentNaming
         public const string Server_8_4 = "SER002";

src/StackExchange.Redis/Interfaces/IDatabase.cs

@@ -1,6 +1,7 @@
 using System;
 using System.Collections.Generic;
 using System.ComponentModel;
+using System.Diagnostics.CodeAnalysis;
 using System.Net;
 
 // ReSharper disable once CheckNamespace
@@ -3174,6 +3175,16 @@ IEnumerable<SortedSetEntry> SortedSetScan(
         /// </remarks>
         long StringDecrement(RedisKey key, long value = 1, CommandFlags flags = CommandFlags.None);
 
+        /// <summary>
+        /// Deletes <paramref name="key"/> if it matches the given <paramref name="when"/> condition.
+        /// </summary>
+        /// <param name="key">The key of the string.</param>
+        /// <param name="when">The condition to enforce.</param>
+        /// <param name="flags">The flags to use for this operation.</param>
+        /// <remarks>See <seealso href="https://redis.io/commands/delex"/>.</remarks>
+        [Experimental(Experiments.Server_8_4, UrlFormat = Experiments.UrlFormat)]
+        bool StringDelete(RedisKey key, ValueCondition when, CommandFlags flags = CommandFlags.None);
+
         /// <summary>
         /// Decrements the string representing a floating point number stored at key by the specified decrement.
         /// If the key does not exist, it is set to 0 before performing the operation.
@@ -3186,6 +3197,15 @@ IEnumerable<SortedSetEntry> SortedSetScan(
         /// <remarks><seealso href="https://redis.io/commands/incrbyfloat"/></remarks>
         double StringDecrement(RedisKey key, double value, CommandFlags flags = CommandFlags.None);
 
+        /// <summary>
+        /// Gets the digest (hash) value of the specified key, represented as a digest equality <see cref="ValueCondition"/>.
+        /// </summary>
+        /// <param name="key">The key of the string.</param>
+        /// <param name="flags">The flags to use for this operation.</param>
+        /// <remarks><seealso href="https://redis.io/commands/digest"/></remarks>
+        [Experimental(Experiments.Server_8_4, UrlFormat = Experiments.UrlFormat)]
+        ValueCondition? StringDigest(RedisKey key, CommandFlags flags = CommandFlags.None);
+
         /// <summary>
         /// Get the value of key. If the key does not exist the special value <see cref="RedisValue.Null"/> is returned.
         /// An error is returned if the value stored at key is not a string, because GET only handles string values.
@@ -3393,6 +3413,20 @@ IEnumerable<SortedSetEntry> SortedSetScan(
         /// <remarks><seealso href="https://redis.io/commands/set"/></remarks>
         bool StringSet(RedisKey key, RedisValue value, TimeSpan? expiry = null, bool keepTtl = false, When when = When.Always, CommandFlags flags = CommandFlags.None);
 
+        /// <summary>
+        /// Set <paramref name="key"/> to hold the string <paramref name="value"/>, if it matches the given <paramref name="when"/> condition.
+        /// </summary>
+        /// <param name="key">The key of the string.</param>
+        /// <param name="value">The value to set.</param>
+        /// <param name="expiry">The expiry to set.</param>
+        /// <param name="when">The condition to enforce.</param>
+        /// <param name="flags">The flags to use for this operation.</param>
+        /// <remarks>See <seealso href="https://redis.io/commands/delex"/>.</remarks>
+        [Experimental(Experiments.Server_8_4, UrlFormat = Experiments.UrlFormat)]
+#pragma warning disable RS0027
+        bool StringSet(RedisKey key, RedisValue value, TimeSpan? expiry, ValueCondition when, CommandFlags flags = CommandFlags.None);
+#pragma warning restore RS0027
+
         /// <summary>
         /// Sets the given keys to their respective values.
         /// If <see cref="When.NotExists"/> is specified, this will not perform any operation at all even if just a single key already exists.

src/StackExchange.Redis/Interfaces/IDatabaseAsync.cs

@@ -1,6 +1,7 @@
 using System;
 using System.Collections.Generic;
 using System.ComponentModel;
+using System.Diagnostics.CodeAnalysis;
 using System.Net;
 using System.Threading.Tasks;
 
@@ -771,9 +772,17 @@ IAsyncEnumerable<SortedSetEntry> SortedSetScanAsync(
         /// <inheritdoc cref="IDatabase.StringDecrement(RedisKey, long, CommandFlags)"/>
         Task<long> StringDecrementAsync(RedisKey key, long value = 1, CommandFlags flags = CommandFlags.None);
 
+        /// <inheritdoc cref="IDatabase.StringDelete(RedisKey, ValueCondition, CommandFlags)"/>
+        [Experimental(Experiments.Server_8_4, UrlFormat = Experiments.UrlFormat)]
+        Task<bool> StringDeleteAsync(RedisKey key, ValueCondition when, CommandFlags flags = CommandFlags.None);
+
         /// <inheritdoc cref="IDatabase.StringDecrement(RedisKey, double, CommandFlags)"/>
         Task<double> StringDecrementAsync(RedisKey key, double value, CommandFlags flags = CommandFlags.None);
 
+        /// <inheritdoc cref="IDatabase.StringDigest(RedisKey, CommandFlags)"/>
+        [Experimental(Experiments.Server_8_4, UrlFormat = Experiments.UrlFormat)]
+        Task<ValueCondition?> StringDigestAsync(RedisKey key, CommandFlags flags = CommandFlags.None);
+
         /// <inheritdoc cref="IDatabase.StringGet(RedisKey, CommandFlags)"/>
         Task<RedisValue> StringGetAsync(RedisKey key, CommandFlags flags = CommandFlags.None);
 
@@ -833,6 +842,12 @@ IAsyncEnumerable<SortedSetEntry> SortedSetScanAsync(
         /// <inheritdoc cref="IDatabase.StringSet(RedisKey, RedisValue, TimeSpan?, bool, When, CommandFlags)"/>
         Task<bool> StringSetAsync(RedisKey key, RedisValue value, TimeSpan? expiry = null, bool keepTtl = false, When when = When.Always, CommandFlags flags = CommandFlags.None);
 
+        /// <inheritdoc cref="IDatabase.StringSet(RedisKey, RedisValue, TimeSpan?, ValueCondition, CommandFlags)"/>
+        [Experimental(Experiments.Server_8_4, UrlFormat = Experiments.UrlFormat)]
+#pragma warning disable RS0027 // Public API with optional parameter(s) should have the most parameters amongst its public overloads
+        Task<bool> StringSetAsync(RedisKey key, RedisValue value, TimeSpan? expiry, ValueCondition when, CommandFlags flags = CommandFlags.None);
+#pragma warning restore RS0027
+
         /// <inheritdoc cref="IDatabase.StringSet(KeyValuePair{RedisKey, RedisValue}[], When, CommandFlags)"/>
         Task<bool> StringSetAsync(KeyValuePair<RedisKey, RedisValue>[] values, When when, CommandFlags flags);
 

src/StackExchange.Redis/KeyspaceIsolation/KeyPrefixed.cs

@@ -732,9 +732,15 @@ public Task<long> StringBitPositionAsync(RedisKey key, bool bit, long start, lon
         public Task<long> StringBitPositionAsync(RedisKey key, bool bit, long start = 0, long end = -1, StringIndexType indexType = StringIndexType.Byte, CommandFlags flags = CommandFlags.None) =>
             Inner.StringBitPositionAsync(ToInner(key), bit, start, end, indexType, flags);
 
+        public Task<bool> StringDeleteAsync(RedisKey key, ValueCondition when, CommandFlags flags = CommandFlags.None) =>
+            Inner.StringDeleteAsync(ToInner(key), when, flags);
+
         public Task<double> StringDecrementAsync(RedisKey key, double value, CommandFlags flags = CommandFlags.None) =>
             Inner.StringDecrementAsync(ToInner(key), value, flags);
 
+        public Task<ValueCondition?> StringDigestAsync(RedisKey key, CommandFlags flags = CommandFlags.None) =>
+            Inner.StringDigestAsync(ToInner(key), flags);
+
         public Task<long> StringDecrementAsync(RedisKey key, long value = 1, CommandFlags flags = CommandFlags.None) =>
             Inner.StringDecrementAsync(ToInner(key), value, flags);
 
@@ -777,6 +783,9 @@ public Task<long> StringIncrementAsync(RedisKey key, long value = 1, CommandFlag
         public Task<long> StringLengthAsync(RedisKey key, CommandFlags flags = CommandFlags.None) =>
             Inner.StringLengthAsync(ToInner(key), flags);
 
+        public Task<bool> StringSetAsync(RedisKey key, RedisValue value, TimeSpan? expiry, ValueCondition when, CommandFlags flags = CommandFlags.None)
+            => Inner.StringSetAsync(ToInner(key), value, expiry, when, flags);
+
         public Task<bool> StringSetAsync(KeyValuePair<RedisKey, RedisValue>[] values, When when = When.Always, CommandFlags flags = CommandFlags.None) =>
             Inner.StringSetAsync(ToInner(values), when, flags);
 

src/StackExchange.Redis/KeyspaceIsolation/KeyPrefixedDatabase.cs

@@ -714,9 +714,15 @@ public long StringBitPosition(RedisKey key, bool bit, long start, long end, Comm
         public long StringBitPosition(RedisKey key, bool bit, long start = 0, long end = -1, StringIndexType indexType = StringIndexType.Byte, CommandFlags flags = CommandFlags.None) =>
             Inner.StringBitPosition(ToInner(key), bit, start, end, indexType, flags);
 
+        public bool StringDelete(RedisKey key, ValueCondition when, CommandFlags flags = CommandFlags.None) =>
+            Inner.StringDelete(ToInner(key), when, flags);
+
         public double StringDecrement(RedisKey key, double value, CommandFlags flags = CommandFlags.None) =>
             Inner.StringDecrement(ToInner(key), value, flags);
 
+        public ValueCondition? StringDigest(RedisKey key, CommandFlags flags = CommandFlags.None) =>
+            Inner.StringDigest(ToInner(key), flags);
+
         public long StringDecrement(RedisKey key, long value = 1, CommandFlags flags = CommandFlags.None) =>
             Inner.StringDecrement(ToInner(key), value, flags);
 
@@ -759,6 +765,9 @@ public long StringIncrement(RedisKey key, long value = 1, CommandFlags flags = C
         public long StringLength(RedisKey key, CommandFlags flags = CommandFlags.None) =>
             Inner.StringLength(ToInner(key), flags);
 
+        public bool StringSet(RedisKey key, RedisValue value, TimeSpan? expiry, ValueCondition when, CommandFlags flags = CommandFlags.None)
+            => Inner.StringSet(ToInner(key), value, expiry, when, flags);
+
         public bool StringSet(KeyValuePair<RedisKey, RedisValue>[] values, When when = When.Always, CommandFlags flags = CommandFlags.None) =>
             Inner.StringSet(ToInner(values), when, flags);