BITFIELD and BITFIELD_RO feature

src/StackExchange.Redis/APITypes/BitfieldSubCommand.cs

@@ -0,0 +1,199 @@
+using System;
+using System.Collections.Generic;
+
+namespace StackExchange.Redis;
+
+/// <summary>
+/// An abstract subcommand for a bitfield.
+/// </summary>
+public abstract class BitfieldSubCommand
+{
+    internal abstract int NumArgs { get; }
+
+    internal abstract void AddArgs(IList<RedisValue> args);
+
+    internal virtual bool IsReadonly => false;
+
+    /// <summary>
+    /// The encoding of the sub-command. A signed or unsigned integer of a given size.
+    /// </summary>
+    public BitfieldEncoding Encoding { get; }
+
+    /// <summary>
+    /// The offset into the bitfield the subcommand will traverse.
+    /// </summary>
+    public BitfieldOffset Offset { get; }
+
+    internal BitfieldSubCommand(BitfieldEncoding encoding, BitfieldOffset offset)
+    {
+        Encoding = encoding;
+        Offset = offset;
+    }
+
+}
+
+/// <summary>
+/// Represents a Bitfield GET, which returns the number stored in the specified offset of a bitfield at the given encoding.
+/// </summary>
+public sealed class BitfieldGet : BitfieldSubCommand
+{
+    /// <summary>
+    /// Initializes a bitfield GET subcommand
+    /// </summary>
+    /// <param name="encoding">The encoding of the subcommand.</param>
+    /// <param name="offset">The offset into the bitfield of the subcommand</param>
+    public BitfieldGet(BitfieldEncoding encoding, BitfieldOffset offset) : base(encoding, offset)
+    {
+    }
+
+    internal override bool IsReadonly => true;
+
+    internal override int NumArgs => 3;
+
+    internal override void AddArgs(IList<RedisValue> args)
+    {
+        args.Add(RedisLiterals.GET);
+        args.Add(Encoding.AsRedisValue);
+        args.Add(Offset.AsRedisValue);
+    }
+}
+
+/// <summary>
+/// Bitfield subcommand which SETs the specified range of bits to the specified value.
+/// </summary>
+public sealed class BitfieldSet : BitfieldSubCommand
+{
+    /// <summary>
+    /// The value to set.
+    /// </summary>
+    public long Value { get; }
+
+    /// <summary>
+    /// Initializes a subcommand for a Bitfield SET.
+    /// </summary>
+    /// <param name="encoding">The number's encoding.</param>
+    /// <param name="offset">The offset into the bitfield to set.</param>
+    /// <param name="value">The value to set.</param>
+    public BitfieldSet(BitfieldEncoding encoding, BitfieldOffset offset, long value) : base(encoding, offset)
+    {
+        Value = value;
+    }
+
+    internal override int NumArgs => 4;
+
+    internal override void AddArgs(IList<RedisValue> args)
+    {
+        args.Add(RedisLiterals.SET);
+        args.Add(Encoding.AsRedisValue);
+        args.Add(Offset.AsRedisValue);
+        args.Add(Value);
+    }
+}
+
+/// <summary>
+/// Bitfield subcommand INCRBY, which increments the number at the specified range of bits by the provided value
+/// </summary>
+public sealed class BitfieldIncrby : BitfieldSubCommand
+{
+    /// <summary>
+    /// The value to increment by.
+    /// </summary>
+    public long Increment { get; }
+
+    /// <summary>
+    /// Determines how overflows are handled for the bitfield.
+    /// </summary>
+    public BitfieldOverflowHandling OverflowHandling { get; }
+
+    /// <summary>
+    /// Initializes a sub-command for a Bitfield INCRBY.
+    /// </summary>
+    /// <param name="encoding">The number's encoding.</param>
+    /// <param name="offset">The offset into the bitfield to set.</param>
+    /// <param name="increment">The value to set.</param>
+    /// <param name="overflowHandling">How overflows will be handled when incrementing.</param>
+    public BitfieldIncrby(BitfieldEncoding encoding, BitfieldOffset offset, long increment, BitfieldOverflowHandling overflowHandling = BitfieldOverflowHandling.Wrap) : base(encoding, offset)
+    {
+        Increment = increment;
+        OverflowHandling = overflowHandling;
+    }
+
+    internal override int NumArgs => OverflowHandling == BitfieldOverflowHandling.Wrap ? 4 : 6;
+
+    internal override void AddArgs(IList<RedisValue> args)
+    {
+        if (OverflowHandling != BitfieldOverflowHandling.Wrap)
+        {
+            args.Add(RedisLiterals.OVERFLOW);
+            args.Add(OverflowHandling.AsRedisValue());
+        }
+        args.Add(RedisLiterals.INCRBY);
+        args.Add(Encoding.AsRedisValue);
+        args.Add(Offset.AsRedisValue);
+        args.Add(Increment);
+    }
+}
+
+
+
+/// <summary>
+/// An offset into a bitfield. This is either a literal offset (number of bits from the beginning of the bitfield) or an
+/// encoding based offset, based off the encoding of the sub-command.
+/// </summary>
+public readonly struct BitfieldOffset
+{
+    /// <summary>
+    /// Returns the BitfieldOffset as a RedisValue
+    /// </summary>
+    internal RedisValue AsRedisValue => $"{(ByEncoding ? "#" : string.Empty)}{Offset}";
+
+    /// <summary>
+    /// Whether or not the BitfieldOffset will work off of the sub-commands integer encoding.
+    /// </summary>
+    public bool ByEncoding { get; }
+
+    /// <summary>
+    /// The number of either bits or encoded integers to offset into the bitfield.
+    /// </summary>
+    public long Offset { get; }
+
+    /// <summary>
+    /// Initializes a bitfield offset
+    /// </summary>
+    /// <param name="byEncoding">Whether or not the BitfieldOffset will work off of the sub-commands integer encoding.</param>
+    /// <param name="offset">The number of either bits or encoded integers to offset into the bitfield.</param>
+    public BitfieldOffset(bool byEncoding, long offset)
+    {
+        ByEncoding = byEncoding;
+        Offset = offset;
+    }
+}
+
+/// <summary>
+/// The encoding that a sub-command should use. This is either a signed or unsigned integer of a specified length.
+/// </summary>
+public readonly struct BitfieldEncoding
+{
+    internal RedisValue AsRedisValue => $"{Signedness.SignChar()}{Size}";
+
+    /// <summary>
+    /// The signedness of the integer.
+    /// </summary>
+    public Signedness Signedness { get; }
+
+    /// <summary>
+    /// The size of the integer.
+    /// </summary>
+    public byte Size { get; }
+
+    /// <summary>
+    /// Initializes the BitfieldEncoding.
+    /// </summary>
+    /// <param name="signedness">The encoding's <see cref="Signedness"/></param>
+    /// <param name="size">The size of the integer.</param>
+    public BitfieldEncoding(Signedness signedness, byte size)
+    {
+        Signedness = signedness;
+        Size = size;
+    }
+}

src/StackExchange.Redis/Enums/BitfieldOverflowHandling.cs

@@ -0,0 +1,33 @@
+using System;
+
+namespace StackExchange.Redis;
+
+/// <summary>
+/// Defines the overflow behavior of a BITFIELD command.
+/// </summary>
+public enum BitfieldOverflowHandling
+{
+    /// <summary>
+    /// Wraps around to the most negative value of signed integers, or zero for unsigned integers
+    /// </summary>
+    Wrap,
+    /// <summary>
+    /// Uses saturation arithmetic, stopping at the highest possible value for overflows, and the lowest possible value for underflows.
+    /// </summary>
+    Saturate,
+    /// <summary>
+    /// If an overflow is encountered, associated subcommand fails, and the result will be NULL.
+    /// </summary>
+    Fail
+}
+
+internal static class BitfieldOverflowHandlingExtensions
+{
+    internal static RedisValue AsRedisValue(this BitfieldOverflowHandling handling) => handling switch
+    {
+        BitfieldOverflowHandling.Fail => RedisLiterals.FAIL,
+        BitfieldOverflowHandling.Saturate => RedisLiterals.SAT,
+        BitfieldOverflowHandling.Wrap => RedisLiterals.WRAP,
+        _ => throw new ArgumentOutOfRangeException(nameof(handling))
+    };
+}

src/StackExchange.Redis/Enums/RedisCommand.cs

@@ -13,6 +13,8 @@ internal enum RedisCommand
     BGREWRITEAOF,
     BGSAVE,
     BITCOUNT,
+    BITFIELD,
+    BITFIELD_RO,
     BITOP,
     BITPOS,
     BLPOP,
@@ -255,6 +257,7 @@ internal static bool IsPrimaryOnly(this RedisCommand command)
             //   for example spreading load via a .DemandReplica flag in the caller.
             // Basically: would it fail on a read-only replica in 100% of cases? Then it goes in the list.
             case RedisCommand.APPEND:
+            case RedisCommand.BITFIELD:
             case RedisCommand.BITOP:
             case RedisCommand.BLPOP:
             case RedisCommand.BRPOP:
@@ -351,6 +354,7 @@ internal static bool IsPrimaryOnly(this RedisCommand command)
             case RedisCommand.BGREWRITEAOF:
             case RedisCommand.BGSAVE:
             case RedisCommand.BITCOUNT:
+            case RedisCommand.BITFIELD_RO:
             case RedisCommand.BITPOS:
             case RedisCommand.CLIENT:
             case RedisCommand.CLUSTER:

src/StackExchange.Redis/Enums/Signedness.cs

@@ -0,0 +1,28 @@
+using System;
+
+namespace StackExchange.Redis;
+
+/// <summary>
+/// Represents an integers signedness
+/// </summary>
+public enum Signedness
+{
+    /// <summary>
+    /// An integer with no sign bit.
+    /// </summary>
+    Unsigned,
+    /// <summary>
+    /// An integer with a sign bit.
+    /// </summary>
+    Signed
+}
+
+internal static class SignednessExtensions
+{
+    internal static char SignChar(this Signedness sign) => sign switch
+    {
+        Signedness.Signed => 'i',
+        Signedness.Unsigned => 'u',
+        _ => throw new ArgumentOutOfRangeException(nameof(sign))
+    };
+}

src/StackExchange.Redis/Interfaces/IDatabase.cs

@@ -2492,6 +2492,56 @@ IEnumerable<SortedSetEntry> SortedSetScan(RedisKey key,
         /// <remarks><seealso href="https://redis.io/commands/bitcount"/></remarks>
         long StringBitCount(RedisKey key, long start = 0, long end = -1, CommandFlags flags = CommandFlags.None);
 
+        /// <summary>
+        /// Pulls a single number out of a bitfield of the provided <paramref name="encoding"/> at the given offset. Will execute a BITFIELD_RO if possible.
+        /// </summary>
+        /// <param name="key">The key for the string.</param>
+        /// <param name="encoding">The encoding of the number.</param>
+        /// <param name="offset">The offset into the bitfield to pull the number from.</param>
+        /// <param name="flags">The Commands for the operation.</param>
+        /// <returns>The number of the given <paramref name="encoding"/> at the provided <paramref name="offset"/>.</returns>
+        /// <remarks><seealso href="https://redis.io/commands/bitfield"/></remarks>
+        /// <remarks><seealso href="https://redis.io/commands/bitfield_ro"/></remarks>
+        long StringBitfieldGet(RedisKey key, BitfieldEncoding encoding, BitfieldOffset offset, CommandFlags flags = CommandFlags.None);
+
+        /// <summary>
+        /// Sets a single number number in a bitfield at the provided <paramref name="offset"/> to the <paramref name="value"/> provided, in the given <paramref name="encoding"/>.
+        /// </summary>
+        /// <param name="key">The key for the string.</param>
+        /// <param name="encoding">The encoding of the number.</param>
+        /// <param name="offset">The offset into the bitfield to pull the number from.</param>
+        /// <param name="value">the value to set the bitfield to.</param>
+        /// <param name="flags">The Commands for the operation.</param>
+        /// <returns>The previous value as am <see cref="Int64"/> at the provided <paramref name="offset"/>.</returns>
+        /// <remarks><seealso href="https://redis.io/commands/bitfield"/></remarks>
+        long StringBitfieldSet(RedisKey key, BitfieldEncoding encoding, BitfieldOffset offset, long value, CommandFlags flags = CommandFlags.None);
+
+
+        /// <summary>
+        /// increments a single number number in a bitfield at the provided <paramref name="offset"/> in the provided <paramref name="encoding"/> by the given <paramref name="increment"/>.
+        /// </summary>
+        /// <param name="key">The key for the string.</param>
+        /// <param name="encoding">The encoding of the number.</param>
+        /// <param name="offset">The offset into the bitfield to pull the number from.</param>
+        /// <param name="increment">the value to increment the bitfield by.</param>
+        /// <param name="overflowHandling">The way integer overflows are handled.</param>
+        /// <param name="flags">The Commands for the operation.</param>
+        /// <returns>The new value of the given at the provided <paramref name="offset"/> after the incrby is applied, represented as an <see cref="Int64"/>. Returns <see langword="null"/> if the operation fails.</returns>
+        /// <remarks><seealso href="https://redis.io/commands/bitfield"/></remarks>
+        long? StringBitfieldIncrement(RedisKey key, BitfieldEncoding encoding, BitfieldOffset offset, long increment, BitfieldOverflowHandling overflowHandling = BitfieldOverflowHandling.Wrap, CommandFlags flags = CommandFlags.None);
+
+
+        /// <summary>
+        /// Executes a set of Bitfield <paramref name="subcommands"/> against the bitfield at the provided <paramref name="key"/>. Will run as a BITFIELD_RO if all operations are read-only and the command is available.
+        /// </summary>
+        /// <param name="key">The key of the string.</param>
+        /// <param name="subcommands">The subcommands to execute against the bitfield.</param>
+        /// <param name="flags">The flags for this operation.</param>
+        /// <returns>An array of numbers corresponding to the result of each sub-command. For increment subcommands, these can be null.</returns>
+        /// <remarks><seealso href="https://redis.io/commands/bitfield"/></remarks>
+        /// <remarks><seealso href="https://redis.io/commands/bitfield_ro"/></remarks>
+        long?[] StringBitfield(RedisKey key, BitfieldSubCommand[] subcommands, CommandFlags flags = CommandFlags.None);
+
         /// <summary>
         /// Perform a bitwise operation between multiple keys (containing string values) and store the result in the destination key.
         /// The BITOP command supports four bitwise operations; note that NOT is a unary operator: the second key should be omitted in this case

src/StackExchange.Redis/Interfaces/IDatabaseAsync.cs

@@ -2445,6 +2445,54 @@ IAsyncEnumerable<SortedSetEntry> SortedSetScanAsync(RedisKey key,
         /// <remarks><seealso href="https://redis.io/commands/bitcount"/></remarks>
         Task<long> StringBitCountAsync(RedisKey key, long start = 0, long end = -1, CommandFlags flags = CommandFlags.None);
 
+        /// <summary>
+        /// Pulls a single number out of a bitfield of the provided <paramref name="encoding"/> at the given offset. Will execute a BITFIELD_RO if possible.
+        /// </summary>
+        /// <param name="key">The key for the string.</param>
+        /// <param name="encoding">The encoding of the number.</param>
+        /// <param name="offset">The offset into the bitfield to pull the number from.</param>
+        /// <param name="flags">The Commands for the operation.</param>
+        /// <returns>The number of the given <paramref name="encoding"/> at the provided <paramref name="offset"/>.</returns>
+        /// <remarks><seealso href="https://redis.io/commands/bitfield"/></remarks>
+        /// <remarks><seealso href="https://redis.io/commands/bitfield_ro"/></remarks>
+        Task<long> StringBitfieldGetAsync(RedisKey key, BitfieldEncoding encoding, BitfieldOffset offset, CommandFlags flags = CommandFlags.None);
+
+        /// <summary>
+        /// Sets a single number number in a bitfield at the provided <paramref name="offset"/> to the <paramref name="value"/> provided, in the given <paramref name="encoding"/>.
+        /// </summary>
+        /// <param name="key">The key for the string.</param>
+        /// <param name="encoding">The encoding of the number.</param>
+        /// <param name="offset">The offset into the bitfield to pull the number from.</param>
+        /// <param name="value">the value to set the bitfield to.</param>
+        /// <param name="flags">The Commands for the operation.</param>
+        /// <returns>The previous value as am <see cref="Int64"/> at the provided <paramref name="offset"/>.</returns>
+        /// <remarks><seealso href="https://redis.io/commands/bitfield"/></remarks>
+        Task<long> StringBitfieldSetAsync(RedisKey key, BitfieldEncoding encoding, BitfieldOffset offset, long value, CommandFlags flags = CommandFlags.None);
+
+        /// <summary>
+        /// Increments a single number number in a bitfield at the provided <paramref name="offset"/> as if it were in the given <parmref name="encoding"/> by the given <paramref name="increment"/>.
+        /// </summary>
+        /// <param name="key">The key for the string.</param>
+        /// <param name="encoding">The encoding of the number.</param>
+        /// <param name="offset">The offset into the bitfield to pull the number from.</param>
+        /// <param name="increment">the value to increment the bitfield by.</param>
+        /// <param name="overflowHandling">The way integer overflows are handled.</param>
+        /// <param name="flags">The Commands for the operation.</param>
+        /// <returns>The new value of the given at the provided <paramref name="offset"/> after the incrby is applied, represented as an <see cref="Int64"/>. Returns <see langword="null"/> if the operation fails.</returns>
+        /// <remarks><seealso href="https://redis.io/commands/bitfield"/></remarks>
+        Task<long?> StringBitfieldIncrementAsync(RedisKey key, BitfieldEncoding encoding, BitfieldOffset offset, long increment, BitfieldOverflowHandling overflowHandling = BitfieldOverflowHandling.Wrap, CommandFlags flags = CommandFlags.None);
+
+        /// <summary>
+        /// Executes a set of Bitfield <paramref name="subcommands"/> against the bitfield at the provided <paramref name="key"/>. Will run as a BITFIELD_RO if all operations are read-only and the command is available.
+        /// </summary>
+        /// <param name="key">The key of the string.</param>
+        /// <param name="subcommands">The subcommands to execute against the bitfield.</param>
+        /// <param name="flags">The flags for this operation.</param>
+        /// <returns>An array of numbers corresponding to the result of each sub-command. For increment subcommands, these can be null.</returns>
+        /// <remarks><seealso href="https://redis.io/commands/bitfield"/></remarks>
+        /// <remarks><seealso href="https://redis.io/commands/bitfield_ro"/></remarks>
+        Task<long?[]> StringBitfieldAsync(RedisKey key, BitfieldSubCommand[] subcommands, CommandFlags flags = CommandFlags.None);
+
         /// <summary>
         /// Perform a bitwise operation between multiple keys (containing string values) and store the result in the destination key.
         /// The BITOP command supports four bitwise operations; note that NOT is a unary operator: the second key should be omitted in this case