Implement GRCA (#3041)

* Implement GRCA (redis/redis#14826)

* Flag [SER006]; remove [SER001]

* release notes

* Update ReleaseNotes.md

Author: mgravell

Directory.Build.props

@@ -10,7 +10,7 @@
     <AllowUnsafeBlocks>true</AllowUnsafeBlocks>
     <CodeAnalysisRuleset>$(MSBuildThisFileDirectory)Shared.ruleset</CodeAnalysisRuleset>
     <MSBuildWarningsAsMessages>NETSDK1069</MSBuildWarningsAsMessages>
-    <NoWarn>$(NoWarn);NU5105;NU1507;SER001;SER002;SER003;SER004;SER005</NoWarn>
+    <NoWarn>$(NoWarn);NU5105;NU1507;SER001;SER002;SER003;SER004;SER005;SER006</NoWarn>
     <PackageReleaseNotes>https://stackexchange.github.io/StackExchange.Redis/ReleaseNotes</PackageReleaseNotes>
     <PackageProjectUrl>https://stackexchange.github.io/StackExchange.Redis/</PackageProjectUrl>
     <PackageLicenseExpression>MIT</PackageLicenseExpression>

docs/ReleaseNotes.md

@@ -8,6 +8,7 @@ Current package versions:
 
 ## Unreleased
 
+- Add [`GCRA`](https://en.wikipedia.org/wiki/Generic_cell_rate_algorithm) support (and remove experimental flag on `VSIM`) ([#3041 by @mgravell](https://github.com/StackExchange/StackExchange.Redis/pull/3041))
 - Add `IServer.GetProductVariant` to detect the product variant and version of the connected server, and use that internally
   to enable multi-DB operations on Valkey clusters ([#3040 by @mgravell](https://github.com/StackExchange/StackExchange.Redis/pull/3040))
 - Ignore cluster nodes with the `handshake` flag ([#3043 by @TimLovellSmith](https://github.com/StackExchange/StackExchange.Redis/pull/3043))

docs/exp/SER006.md

@@ -0,0 +1,24 @@
+Redis 8.8 is currently in preview and may be subject to change.
+
+New features in Redis 8.8:
+
+- `GCRA` for rate-limiting  
+
+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. 
+
+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:
+
+```xml
+<NoWarn>$(NoWarn);SER006</NoWarn>
+```
+
+or more granularly / locally in C#:
+
+``` c#
+#pragma warning disable SER006
+```

src/RESPite/Messages/RespReader.cs

@@ -1852,30 +1852,54 @@ public readonly decimal ReadDecimal()
     }
 
     /// <summary>
-    /// Read the current element as a <see cref="bool"/> value.
+    /// Try to read the current element as a <see cref="bool"/> value.
     /// </summary>
-    public readonly bool ReadBoolean()
+    /// <param name="value">The parsed boolean value if successful.</param>
+    /// <returns>True if the value was successfully parsed; false otherwise.</returns>
+    public readonly bool TryReadBoolean(out bool value)
     {
         var span = Buffer(stackalloc byte[2]);
         switch (span.Length)
         {
             case 1:
                 switch (span[0])
                 {
-                    case (byte)'0' when Prefix == RespPrefix.Integer: return false;
-                    case (byte)'1' when Prefix == RespPrefix.Integer: return true;
-                    case (byte)'f' when Prefix == RespPrefix.Boolean: return false;
-                    case (byte)'t' when Prefix == RespPrefix.Boolean: return true;
+                    case (byte)'0' when Prefix == RespPrefix.Integer:
+                        value = false;
+                        return true;
+                    case (byte)'1' when Prefix == RespPrefix.Integer:
+                        value = true;
+                        return true;
+                    case (byte)'f' when Prefix == RespPrefix.Boolean:
+                        value = false;
+                        return true;
+                    case (byte)'t' when Prefix == RespPrefix.Boolean:
+                        value = true;
+                        return true;
                 }
 
                 break;
-            case 2 when Prefix == RespPrefix.SimpleString && IsOK(): return true;
+            case 2 when Prefix == RespPrefix.SimpleString && IsOK():
+                value = true;
+                return true;
         }
 
-        ThrowFormatException();
+        value = false;
         return false;
     }
 
+    /// <summary>
+    /// Read the current element as a <see cref="bool"/> value.
+    /// </summary>
+    public readonly bool ReadBoolean()
+    {
+        if (!TryReadBoolean(out var value))
+        {
+            ThrowFormatException();
+        }
+        return value;
+    }
+
     /// <summary>
     /// Parse a scalar value as an enum of type <typeparamref name="T"/>.
     /// </summary>

src/RESPite/PublicAPI/PublicAPI.Unshipped.txt

@@ -155,6 +155,7 @@
 [SER004]RESPite.Messages.RespReader.ProtocolBytesRemaining.get -> long
 [SER004]RESPite.Messages.RespReader.ReadArray<TResult>(RESPite.Messages.RespReader.Projection<TResult>! projection, bool scalar = false) -> TResult[]?
 [SER004]RESPite.Messages.RespReader.ReadBoolean() -> bool
+[SER004]RESPite.Messages.RespReader.TryReadBoolean(out bool value) -> bool
 [SER004]RESPite.Messages.RespReader.ReadByteArray() -> byte[]?
 [SER004]RESPite.Messages.RespReader.ReadDecimal() -> decimal
 [SER004]RESPite.Messages.RespReader.ReadDouble() -> double

src/RESPite/Shared/Experiments.cs

@@ -8,11 +8,11 @@ internal static class Experiments
         public const string UrlFormat = "https://stackexchange.github.io/StackExchange.Redis/exp/";
 
         // ReSharper disable InconsistentNaming
-        public const string VectorSets = "SER001";
         public const string Server_8_4 = "SER002";
         public const string Server_8_6 = "SER003";
         public const string Respite = "SER004";
         public const string UnitTesting = "SER005";
+        public const string Server_8_8 = "SER006";
         // ReSharper restore InconsistentNaming
     }
 }

src/StackExchange.Redis/ChannelMessageQueue.cs

@@ -1,5 +1,4 @@
 using System;
-using System.Buffers.Text;
 using System.Collections.Generic;
 using System.Threading;
 using System.Threading.Channels;

src/StackExchange.Redis/Enums/RedisCommand.cs

@@ -60,6 +60,7 @@ internal enum RedisCommand
     GEOSEARCH,
     GEOSEARCHSTORE,
 
+    GCRA,
     GET,
     GETBIT,
     GETDEL,
@@ -323,6 +324,7 @@ internal static bool IsPrimaryOnly(this RedisCommand command)
             case RedisCommand.EXPIREAT:
             case RedisCommand.FLUSHALL:
             case RedisCommand.FLUSHDB:
+            case RedisCommand.GCRA:
             case RedisCommand.GEOSEARCHSTORE:
             case RedisCommand.GETDEL:
             case RedisCommand.GETEX:

src/StackExchange.Redis/ExtensionMethods.cs

@@ -7,8 +7,10 @@
 using System.Security.Authentication;
 using System.Security.Cryptography.X509Certificates;
 using System.Text;
+using System.Threading;
 using System.Threading.Tasks;
 using Pipelines.Sockets.Unofficial.Arenas;
+using RESPite;
 
 namespace StackExchange.Redis
 {
@@ -337,5 +339,70 @@ internal static int VectorSafeIndexOfCRLF(this ReadOnlySpan<byte> span)
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
         internal static TTo[]? ToArray<TTo, TState>(in this RawResult result, Projection<RawResult, TState, TTo> selector, in TState state)
             => result.IsNull ? null : result.GetItems().ToArray(selector, in state);
+
+        /// <summary>
+        /// Attempts to acquire a GCRA rate limit token, retrying with delays if rate limited.
+        /// </summary>
+        /// <param name="database">The database instance.</param>
+        /// <param name="key">The key for the rate limiter.</param>
+        /// <param name="maxBurst">The maximum burst size.</param>
+        /// <param name="requestsPerPeriod">The number of requests allowed per period.</param>
+        /// <param name="allow">The maximum time to wait for a successful acquisition.</param>
+        /// <param name="periodSeconds">The period in seconds (default: 1.0).</param>
+        /// <param name="count">The number of tokens to acquire (default: 1).</param>
+        /// <param name="flags">The command flags to use.</param>
+        /// <param name="cancellationToken">The cancellation token.</param>
+        /// <returns>True if the token was acquired within the allowed time; false otherwise.</returns>
+        [Experimental(Experiments.Server_8_8, UrlFormat = Experiments.UrlFormat)]
+        public static async ValueTask<bool> TryAcquireGcraAsync(
+            this IDatabaseAsync database,
+            RedisKey key,
+            int maxBurst,
+            int requestsPerPeriod,
+            TimeSpan allow,
+            double periodSeconds = 1.0,
+            int count = 1,
+            CommandFlags flags = CommandFlags.None,
+            CancellationToken cancellationToken = default)
+        {
+            cancellationToken.ThrowIfCancellationRequested();
+
+            var startTime = DateTime.UtcNow;
+            var allowMilliseconds = allow.TotalMilliseconds;
+
+            while (true)
+            {
+                var result = await database.StringGcraRateLimitAsync(key, maxBurst, requestsPerPeriod, periodSeconds, count, flags).ConfigureAwait(false);
+
+                if (!result.Limited)
+                {
+                    return true;
+                }
+
+                var elapsed = (DateTime.UtcNow - startTime).TotalMilliseconds;
+                var remaining = allowMilliseconds - elapsed;
+
+                if (remaining <= 0)
+                {
+                    return false;
+                }
+
+                var delaySeconds = result.RetryAfterSeconds;
+                if (delaySeconds <= 0)
+                {
+                    // Shouldn't happen when Limited is true, but handle defensively
+                    return false;
+                }
+
+                var delayMilliseconds = delaySeconds * 1000.0;
+                if (delayMilliseconds > remaining)
+                {
+                    // Not enough time left to wait for retry
+                    return false;
+                }
+
+                await Task.Delay(TimeSpan.FromSeconds(delaySeconds), cancellationToken).ConfigureAwait(false);
+            }
+        }
     }
 }

src/StackExchange.Redis/Gcra.GcraMessage.cs

@@ -0,0 +1,40 @@
+namespace StackExchange.Redis;
+
+internal partial class RedisDatabase
+{
+    internal sealed class GcraMessage(
+        int database,
+        CommandFlags flags,
+        RedisKey key,
+        int maxBurst,
+        int requestsPerPeriod,
+        double periodSeconds,
+        int count) : Message(database, flags, RedisCommand.GCRA)
+    {
+        protected override void WriteImpl(PhysicalConnection connection)
+        {
+            // GCRA key max_burst requests_per_period period [NUM_REQUESTS count]
+            connection.WriteHeader(Command, ArgCount);
+            connection.WriteBulkString(key);
+            connection.WriteBulkString(maxBurst);
+            connection.WriteBulkString(requestsPerPeriod);
+            connection.WriteBulkString(periodSeconds);
+
+            if (count != 1)
+            {
+                connection.WriteBulkString("NUM_REQUESTS"u8);
+                connection.WriteBulkString(count);
+            }
+        }
+
+        public override int ArgCount
+        {
+            get
+            {
+                int argCount = 4; // key, max_burst, requests_per_period, period
+                if (count != 1) argCount += 2; // NUM_REQUESTS, count
+                return argCount;
+            }
+        }
+    }
+}