Add support for BZMPOP (#233)

Add support for the BZMPOP command.

This command is blocking on the server, so it goes against the current
policy of the StackExchange.Redis library. Therefore make it obvious in
the code documentation that attention must be given to the timeout in
the connection multiplexer.

The StackExchange.Redis library already defines a type for the payload
returned by BZMPOP (which is the same as for ZMPOP), namely the
SortedSetPopResult class. However, the constructor of that class is
internal in the library, so we can't create instances of it. Therefore
roll our out type for a <value, score> pair, and use Tuple to pair a key
with a list of such <value, score> pairs.

Author: Gabriel Erzse

src/NRedisStack/CoreCommands/CoreCommandBuilder.cs

@@ -1,6 +1,8 @@
 using NRedisStack.RedisStackCommands;
 using NRedisStack.Core.Literals;
 using NRedisStack.Core;
+using NRedisStack.Core.DataTypes;
+using StackExchange.Redis;
 
 namespace NRedisStack
 {
@@ -18,5 +20,28 @@ public static SerializedCommand ClientSetInfo(SetInfoAttr attr, string value)
 
             return new SerializedCommand(RedisCoreCommands.CLIENT, RedisCoreCommands.SETINFO, attrValue, value);
         }
+
+        public static SerializedCommand BzmPop(int timeout, RedisKey[] keys, MinMaxModifier minMaxModifier, long? count)
+        {
+            if (keys.Length == 0)
+            {
+                throw new ArgumentException("At least one key must be provided.");
+            }
+
+            List<object> args = new List<object>();
+
+            args.Add(timeout);
+            args.Add(keys.Length);
+            args.AddRange(keys.Cast<object>());
+            args.Add(minMaxModifier == MinMaxModifier.Min ? CoreArgs.MIN : CoreArgs.MAX);
+
+            if (count != null)
+            {
+                args.Add(CoreArgs.COUNT);
+                args.Add(count);
+            }
+
+            return new SerializedCommand(RedisCoreCommands.BZMPOP, args);
+        }
     }
 }

src/NRedisStack/CoreCommands/CoreCommands.cs

@@ -1,5 +1,7 @@
 using NRedisStack.Core;
+using NRedisStack.Core.DataTypes;
 using StackExchange.Redis;
+
 namespace NRedisStack
 {
 
@@ -19,5 +21,61 @@ public static bool ClientSetInfo(this IDatabase db, SetInfoAttr attr, string val
                 return false;
             return db.Execute(CoreCommandBuilder.ClientSetInfo(attr, value)).OKtoBoolean();
         }
+
+        /// <summary>
+        /// The BZMPOP command.
+        /// <p/>
+        /// Removes and returns up to <paramref name="count"/> entries from the first non-empty sorted set in
+        /// <paramref name="keys"/>. If none of the sets contain elements, the call blocks on the server until elements
+        /// become available or the given <paramref name="timeout"/> passes. A <paramref name="timeout"/> of <c>0</c>
+        /// means to wait indefinitely server-side. Returns <c>null</c> if the server timeout expires. 
+        /// <p/>
+        /// When using this, pay attention to the timeout configured on the <see cref="ConnectionMultiplexer"/>, which
+        /// by default can be too small, in which case you want to increase it:
+        /// <code>
+        /// ConfigurationOptions configurationOptions = new ConfigurationOptions();
+        /// configurationOptions.SyncTimeout = 120000; // set a meaningful value here
+        /// configurationOptions.EndPoints.Add("localhost");
+        /// ConnectionMultiplexer redis = ConnectionMultiplexer.Connect(configurationOptions);
+        /// </code>
+        /// If the connection multiplexer timeout expires, a <c>StackExchange.Redis.RedisTimeoutException</c> will be
+        /// thrown.
+        /// <p/>
+        /// This is an extension method added to the <see cref="IDatabase"/> class, for convenience.
+        /// </summary>
+        /// <param name="db">The <see cref="IDatabase"/> class where this extension method is applied.</param>
+        /// <param name="timeout">Server-side timeout for the wait. A value of <c>0</c> means to wait indefinitely.</param>
+        /// <param name="keys">The keys to check.</param>
+        /// <param name="minMaxModifier">Specify from which end of the sorted set to pop values. If set to <c>MinMaxModifier.Min</c>
+        /// then the minimum elements will be popped, otherwise the maximum values.</param>
+        /// <param name="count">The maximum number of records to pop out. If set to <c>null</c> then the server default
+        /// will be used.</param>
+        /// <returns>A collection of sorted set entries paired with their scores, together with the key they were popped
+        /// from, or <c>null</c> if the server timeout expires.</returns>
+        /// <remarks><seealso href="https://redis.io/commands/bzmpop"/></remarks>
+        public static Tuple<RedisKey, List<RedisValueWithScore>>? BzmPop(this IDatabase db, int timeout, RedisKey[] keys, MinMaxModifier minMaxModifier, long? count = null)
+        {
+            var command = CoreCommandBuilder.BzmPop(timeout, keys, minMaxModifier, count);
+            return db.Execute(command).ToSortedSetPopResult();
+        }
+
+        /// <summary>
+        /// Syntactic sugar for <see cref="BzmPop(StackExchange.Redis.IDatabase,int,StackExchange.Redis.RedisKey[],StackExchange.Redis.Order,System.Nullable{long})"/>,
+        /// where only one key is used.
+        /// </summary>
+        /// <param name="db">The <see cref="IDatabase"/> class where this extension method is applied.</param>
+        /// <param name="timeout">Server-side timeout for the wait. A value of <c>0</c> means to wait indefinitely.</param>
+        /// <param name="key">The key to check.</param>
+        /// <param name="minMaxModifier">Specify from which end of the sorted set to pop values. If set to <c>MinMaxModifier.Min</c>
+        /// then the minimum elements will be popped, otherwise the maximum values.</param>
+        /// <param name="count">The maximum number of records to pop out. If set to <c>null</c> then the server default
+        /// will be used.</param>
+        /// <returns>A collection of sorted set entries paired with their scores, together with the key they were popped
+        /// from, or <c>null</c> if the server timeout expires.</returns>
+        /// <remarks><seealso href="https://redis.io/commands/bzmpop"/></remarks>
+        public static Tuple<RedisKey, List<RedisValueWithScore>>? BzmPop(this IDatabase db, int timeout, RedisKey key, MinMaxModifier minMaxModifier, long? count = null)
+        {
+            return BzmPop(db, timeout, new[] { key }, minMaxModifier, count);
+        }
     }
 }

src/NRedisStack/CoreCommands/DataTypes/MinMaxModifier.cs

@@ -0,0 +1,35 @@
+using StackExchange.Redis;
+
+namespace NRedisStack.Core.DataTypes;
+
+/// <summary>
+/// Modifier that can be used for sorted set commands, where a MIN/MAX argument is expected by the Redis server.
+/// </summary>
+public enum MinMaxModifier
+{
+    /// <summary>
+    /// Maps to the <c>MIN</c> argument on the Redis server.
+    /// </summary>
+    Min,
+
+    /// <summary>
+    /// Maps to the <c>MAX</c> argument on the Redis server.
+    /// </summary>
+    Max
+}
+
+/// <summary>
+/// Conversion methods from/to other common data types.
+/// </summary>
+public static class MinMaxModifierExtensions
+{
+    /// <summary>
+    /// Convert from <see cref="Order"/> to <see cref="MinMaxModifier"/>.
+    /// </summary>
+    public static MinMaxModifier ToMinMax(this Order order) => order switch
+    {
+        Order.Ascending => MinMaxModifier.Min,
+        Order.Descending => MinMaxModifier.Max,
+        _ => throw new ArgumentOutOfRangeException(nameof(order))
+    };
+}

src/NRedisStack/CoreCommands/DataTypes/RedisValueWithScore.cs

@@ -0,0 +1,31 @@
+using StackExchange.Redis;
+
+namespace NRedisStack.Core.DataTypes;
+
+/// <summary>
+/// Holds a <see cref="RedisValue"/> with an associated score.
+/// Used when working with sorted sets.
+/// </summary>
+public struct RedisValueWithScore
+{
+    /// <summary>
+    /// Pair a <see cref="RedisValue"/> with a numeric score.
+    /// </summary>
+    public RedisValueWithScore(RedisValue value, double score)
+    {
+        Value = value;
+        Score = score;
+    }
+
+    /// <summary>
+    /// The value of an item stored in a sorted set. For example, in the Redis command
+    /// <c>ZADD my-set 5.1 my-value</c>, the value is <c>my-value</c>.
+    /// </summary>
+    public RedisValue Value { get; }
+
+    /// <summary>
+    /// The score of an item stored in a sorted set. For example, in the Redis command
+    /// <c>ZADD my-set 5.1 my-value</c>, the score is <c>5.1</c>.
+    /// </summary>
+    public double Score { get; }
+}

src/NRedisStack/CoreCommands/Literals/CommandArgs.cs

@@ -1,8 +1,11 @@
 namespace NRedisStack.Core.Literals
 {
-    internal class CoreArgs
+    internal static class CoreArgs
     {
+        public const string COUNT = "COUNT";
         public const string lib_name = "LIB-NAME";
         public const string lib_ver = "LIB-VER";
+        public const string MAX = "MAX";
+        public const string MIN = "MIN";
     }
 }

src/NRedisStack/CoreCommands/Literals/Commands.cs

@@ -3,8 +3,9 @@ namespace NRedisStack.Core.Literals
     /// <summary>
     /// Redis Core command literals
     /// </summary>
-    internal class RedisCoreCommands
+    internal static class RedisCoreCommands
     {
+        public const string BZMPOP = "BZMPOP";
         public const string CLIENT = "CLIENT";
         public const string SETINFO = "SETINFO";
     }

src/NRedisStack/ResponseParser.cs

@@ -3,6 +3,7 @@
 using NRedisStack.Extensions;
 using StackExchange.Redis;
 using NRedisStack.Bloom.DataTypes;
+using NRedisStack.Core.DataTypes;
 using NRedisStack.CuckooFilter.DataTypes;
 using NRedisStack.CountMinSketch.DataTypes;
 using NRedisStack.TopK.DataTypes;
@@ -84,6 +85,16 @@ public static TimeStamp ToTimeStamp(this RedisResult result)
             return new TimeStamp((long)result);
         }
 
+        public static RedisKey ToRedisKey(this RedisResult result)
+        {
+            return new RedisKey(result.ToString());
+        }
+
+        public static RedisValue ToRedisValue(this RedisResult result)
+        {
+            return new RedisValue(result.ToString());
+        }
+
         public static IReadOnlyList<TimeStamp> ToTimeStampArray(this RedisResult result)
         {
             RedisResult[] redisResults = (RedisResult[])result!;
@@ -715,5 +726,29 @@ public static Dictionary<string, RedisResult>[] ToDictionarys(this RedisResult r
             return dicts;
 
         }
+
+        public static Tuple<RedisKey, List<RedisValueWithScore>>? ToSortedSetPopResult(this RedisResult result)
+        {
+            if (result.IsNull)
+            {
+                return null;
+            }
+
+            var resultArray = (RedisResult[])result!;
+            var resultKey = resultArray[0].ToRedisKey();
+            var resultSetItems = resultArray[1].ToArray();
+
+            List<RedisValueWithScore> valuesWithScores = new List<RedisValueWithScore>();
+
+            foreach (var resultSetItem in resultSetItems)
+            {
+                var resultSetItemArray = (RedisResult[])resultSetItem!;
+                var value = resultSetItemArray[0].ToRedisValue();
+                var score = resultSetItemArray[1].ToDouble();
+                valuesWithScores.Add(new RedisValueWithScore(value, score));
+            }
+
+            return new Tuple<RedisKey, List<RedisValueWithScore>>(resultKey, valuesWithScores);
+        }
     }
 }