GCRA: reflect name/protocol change from redis/redis#14950 (note: need a new CI build before we can validate this)

Author: mgravell

docs/ReleaseNotes.md

@@ -8,7 +8,7 @@ Current package versions:
 
 ## Unreleased
 
-- (none)
+- Update experimental `GCRA` APIs and wire protocol terminology from "requests" to "tokens", to match server change ([#PR by @mgravell](https://github.com/StackExchange/StackExchange.Redis/pull/PR))
 
 ## 2.12.14
 

src/StackExchange.Redis/ExtensionMethods.cs

@@ -346,7 +346,7 @@ internal static int VectorSafeIndexOfCRLF(this ReadOnlySpan<byte> span)
         /// <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="tokensPerPeriod">The number of tokens 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>
@@ -358,7 +358,7 @@ public static async ValueTask<bool> TryAcquireGcraAsync(
             this IDatabaseAsync database,
             RedisKey key,
             int maxBurst,
-            int requestsPerPeriod,
+            int tokensPerPeriod,
             TimeSpan allow,
             double periodSeconds = 1.0,
             int count = 1,
@@ -372,7 +372,7 @@ public static async ValueTask<bool> TryAcquireGcraAsync(
 
             while (true)
             {
-                var result = await database.StringGcraRateLimitAsync(key, maxBurst, requestsPerPeriod, periodSeconds, count, flags).ConfigureAwait(false);
+                var result = await database.StringGcraRateLimitAsync(key, maxBurst, tokensPerPeriod, periodSeconds, count, flags).ConfigureAwait(false);
 
                 if (!result.Limited)
                 {

src/StackExchange.Redis/Gcra.GcraMessage.cs

@@ -7,22 +7,22 @@ internal sealed class GcraMessage(
         CommandFlags flags,
         RedisKey key,
         int maxBurst,
-        int requestsPerPeriod,
+        int tokensPerPeriod,
         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]
+            // GCRA key max_burst tokens_per_period period [TOKENS count]
             connection.WriteHeader(Command, ArgCount);
             connection.WriteBulkString(key);
             connection.WriteBulkString(maxBurst);
-            connection.WriteBulkString(requestsPerPeriod);
+            connection.WriteBulkString(tokensPerPeriod);
             connection.WriteBulkString(periodSeconds);
 
             if (count != 1)
             {
-                connection.WriteBulkString("NUM_REQUESTS"u8);
+                connection.WriteBulkString("TOKENS"u8);
                 connection.WriteBulkString(count);
             }
         }
@@ -31,8 +31,8 @@ public override int ArgCount
         {
             get
             {
-                int argCount = 4; // key, max_burst, requests_per_period, period
-                if (count != 1) argCount += 2; // NUM_REQUESTS, count
+                int argCount = 4; // key, max_burst, tokens_per_period, period
+                if (count != 1) argCount += 2; // TOKENS, count
                 return argCount;
             }
         }

src/StackExchange.Redis/Gcra.GcraRateLimitResult.cs

@@ -10,23 +10,23 @@ namespace StackExchange.Redis;
 public readonly partial struct GcraRateLimitResult
 {
     /// <summary>
-    /// Indicates whether the request was rate limited (true) or allowed (false).
+    /// Indicates whether the token acquisition was rate limited (true) or allowed (false).
     /// </summary>
     public bool Limited { get; }
 
     /// <summary>
-    /// The maximum number of requests allowed. Always equal to max_burst + 1.
+    /// The maximum number of tokens allowed. Always equal to max_burst + 1.
     /// </summary>
-    public int MaxRequests { get; }
+    public int MaxTokens { get; }
 
     /// <summary>
-    /// The number of requests available immediately without being rate limited.
+    /// The number of tokens available immediately without being rate limited.
     /// </summary>
-    public int AvailableRequests { get; }
+    public int AvailableTokens { get; }
 
     /// <summary>
     /// The number of seconds after which the caller should retry.
-    /// Returns -1 if the request is not limited.
+    /// Returns -1 if the token acquisition is not limited.
     /// </summary>
     public int RetryAfterSeconds { get; }
 
@@ -38,11 +38,11 @@ public readonly partial struct GcraRateLimitResult
     /// <summary>
     /// Initializes a new instance of the <see cref="GcraRateLimitResult"/> struct.
     /// </summary>
-    public GcraRateLimitResult(bool limited, int maxRequests, int availableRequests, int retryAfterSeconds, int fullBurstAfterSeconds)
+    public GcraRateLimitResult(bool limited, int maxTokens, int availableTokens, int retryAfterSeconds, int fullBurstAfterSeconds)
     {
         Limited = limited;
-        MaxRequests = maxRequests;
-        AvailableRequests = availableRequests;
+        MaxTokens = maxTokens;
+        AvailableTokens = availableTokens;
         RetryAfterSeconds = retryAfterSeconds;
         FullBurstAfterSeconds = fullBurstAfterSeconds;
     }

src/StackExchange.Redis/Gcra.ResultProcessor.cs

@@ -10,23 +10,23 @@ protected override bool SetResultCore(PhysicalConnection connection, Message mes
         {
             // GCRA returns an array with 5 elements:
             // 1) <limited> # 0 or 1
-            // 2) <max-req-num> # max number of request. Always equal to max_burst+1
-            // 3) <num-avail-req> # number of requests available immediately
-            // 4) <reply-after> # number of seconds after which caller should retry. Always returns -1 if request isn't limited.
+            // 2) <max-token-num> # max number of tokens. Always equal to max_burst+1
+            // 3) <num-avail-token> # number of tokens available immediately
+            // 4) <reply-after> # number of seconds after which caller should retry. Always returns -1 if acquisition isn't limited.
             // 5) <full-burst-after> # number of seconds after which a full burst will be allowed
             if (result.Resp2TypeArray == ResultType.Array && result.ItemsCount >= 5)
             {
                 var items = result.GetItems();
                 bool limited = items[0].GetBoolean();
-                if (items[1].TryGetInt64(out long maxRequests)
-                    && items[2].TryGetInt64(out long availableRequests)
+                if (items[1].TryGetInt64(out long maxTokens)
+                    && items[2].TryGetInt64(out long availableTokens)
                     && items[3].TryGetInt64(out long retryAfterSeconds)
                     && items[4].TryGetInt64(out long fullBurstAfterSeconds))
                 {
                     var grca = new GcraRateLimitResult(
                         limited: limited,
-                        maxRequests: (int)maxRequests,
-                        availableRequests: (int)availableRequests,
+                        maxTokens: (int)maxTokens,
+                        availableTokens: (int)availableTokens,
                         retryAfterSeconds: (int)retryAfterSeconds,
                         fullBurstAfterSeconds: (int)fullBurstAfterSeconds);
                     SetResult(message, grca);
@@ -42,21 +42,21 @@ protected override bool SetResultCore(PhysicalConnection connection, Message mes
         {
             // GCRA returns an array with 5 elements:
             // 1) <limited> # 0 or 1
-            // 2) <max-req-num> # max number of request. Always equal to max_burst+1
-            // 3) <num-avail-req> # number of requests available immediately
-            // 4) <reply-after> # number of seconds after which caller should retry. Always returns -1 if request isn't limited.
+            // 2) <max-token-num> # max number of tokens. Always equal to max_burst+1
+            // 3) <num-avail-token> # number of tokens available immediately
+            // 4) <reply-after> # number of seconds after which caller should retry. Always returns -1 if acquisition isn't limited.
             // 5) <full-burst-after> # number of seconds after which a full burst will be allowed
             if (reader.IsAggregate
                 && reader.TryMoveNext() && reader.IsScalar && reader.TryReadBoolean(out bool limited)
-                && reader.TryMoveNext() && reader.IsScalar && reader.TryReadInt64(out long maxRequests)
-                && reader.TryMoveNext() && reader.IsScalar && reader.TryReadInt64(out long availableRequests)
+                && reader.TryMoveNext() && reader.IsScalar && reader.TryReadInt64(out long maxTokens)
+                && reader.TryMoveNext() && reader.IsScalar && reader.TryReadInt64(out long availableTokens)
                 && reader.TryMoveNext() && reader.IsScalar && reader.TryReadInt64(out long retryAfterSeconds)
                 && reader.TryMoveNext() && reader.IsScalar && reader.TryReadInt64(out long fullBurstAfterSeconds))
             {
                 var result = new GcraRateLimitResult(
                     limited: limited,
-                    maxRequests: (int)maxRequests,
-                    availableRequests: (int)availableRequests,
+                    maxTokens: (int)maxTokens,
+                    availableTokens: (int)availableTokens,
                     retryAfterSeconds: (int)retryAfterSeconds,
                     fullBurstAfterSeconds: (int)fullBurstAfterSeconds);
                 SetResult(message, result);

src/StackExchange.Redis/Interfaces/IDatabase.cs

@@ -3259,14 +3259,14 @@ IEnumerable<SortedSetEntry> SortedSetScan(
         /// </summary>
         /// <param name="key">The key to rate limit.</param>
         /// <param name="maxBurst">The maximum burst size.</param>
-        /// <param name="requestsPerPeriod">The number of requests allowed per period.</param>
+        /// <param name="tokensPerPeriod">The number of tokens allowed per period.</param>
         /// <param name="periodSeconds">The period duration in seconds. Default is 1.0.</param>
-        /// <param name="count">The number of requests to consume. Default is 1.</param>
+        /// <param name="count">The number of tokens to consume. Default is 1.</param>
         /// <param name="flags">The flags to use for this operation.</param>
         /// <returns>A <see cref="GcraRateLimitResult"/> containing the rate limit decision and metadata.</returns>
         /// <remarks><seealso href="https://redis.io/commands/gcra"/></remarks>
         [Experimental(Experiments.Server_8_8, UrlFormat = Experiments.UrlFormat)]
-        GcraRateLimitResult StringGcraRateLimit(RedisKey key, int maxBurst, int requestsPerPeriod, double periodSeconds = 1.0, int count = 1, CommandFlags flags = CommandFlags.None);
+        GcraRateLimitResult StringGcraRateLimit(RedisKey key, int maxBurst, int tokensPerPeriod, double periodSeconds = 1.0, int count = 1, 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.

src/StackExchange.Redis/Interfaces/IDatabaseAsync.cs

@@ -797,7 +797,7 @@ IAsyncEnumerable<SortedSetEntry> SortedSetScanAsync(
 
         /// <inheritdoc cref="IDatabase.StringGcraRateLimit(RedisKey, int, int, double, int, CommandFlags)"/>
         [Experimental(Experiments.Server_8_8, UrlFormat = Experiments.UrlFormat)]
-        Task<GcraRateLimitResult> StringGcraRateLimitAsync(RedisKey key, int maxBurst, int requestsPerPeriod, double periodSeconds = 1.0, int count = 1, CommandFlags flags = CommandFlags.None);
+        Task<GcraRateLimitResult> StringGcraRateLimitAsync(RedisKey key, int maxBurst, int tokensPerPeriod, double periodSeconds = 1.0, int count = 1, CommandFlags flags = CommandFlags.None);
 
         /// <inheritdoc cref="IDatabase.StringGet(RedisKey, CommandFlags)"/>
         Task<RedisValue> StringGetAsync(RedisKey key, CommandFlags flags = CommandFlags.None);

src/StackExchange.Redis/KeyspaceIsolation/KeyPrefixed.cs

@@ -792,8 +792,8 @@ 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<GcraRateLimitResult> StringGcraRateLimitAsync(RedisKey key, int maxBurst, int requestsPerPeriod, double period = 1.0, int count = 1, CommandFlags flags = CommandFlags.None) =>
-            Inner.StringGcraRateLimitAsync(ToInner(key), maxBurst, requestsPerPeriod, period, count, flags);
+        public Task<GcraRateLimitResult> StringGcraRateLimitAsync(RedisKey key, int maxBurst, int tokensPerPeriod, double period = 1.0, int count = 1, CommandFlags flags = CommandFlags.None) =>
+            Inner.StringGcraRateLimitAsync(ToInner(key), maxBurst, tokensPerPeriod, period, count, flags);
 
         public Task<bool> StringSetAsync(RedisKey key, RedisValue value, Expiration expiry, ValueCondition when, CommandFlags flags = CommandFlags.None)
             => Inner.StringSetAsync(ToInner(key), value, expiry, when, flags);

src/StackExchange.Redis/KeyspaceIsolation/KeyPrefixedDatabase.cs

@@ -774,8 +774,8 @@ 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 GcraRateLimitResult StringGcraRateLimit(RedisKey key, int maxBurst, int requestsPerPeriod, double period = 1.0, int count = 1, CommandFlags flags = CommandFlags.None) =>
-            Inner.StringGcraRateLimit(ToInner(key), maxBurst, requestsPerPeriod, period, count, flags);
+        public GcraRateLimitResult StringGcraRateLimit(RedisKey key, int maxBurst, int tokensPerPeriod, double period = 1.0, int count = 1, CommandFlags flags = CommandFlags.None) =>
+            Inner.StringGcraRateLimit(ToInner(key), maxBurst, tokensPerPeriod, period, count, flags);
 
         public bool StringSet(RedisKey key, RedisValue value, Expiration expiry, ValueCondition when, CommandFlags flags = CommandFlags.None)
             => Inner.StringSet(ToInner(key), value, expiry, when, flags);