Fix RESP3 map parsing for FT.SEARCH/AGGREGATE/INFO (#570) (#571)

Newer StackExchange.Redis versions auto-negotiate RESP3, which changes
FT.SEARCH/FT.AGGREGATE/FT.INFO replies from the flat RESP2 array into a
map. SE.Redis collapses a map's Resp2Type to Array (flattened key/value
pairs), so the existing parsers read the first map key as the document
count, throwing "InvalidCastException: Could not cast to long".

Detect the RESP3 map shape at the parser layer and reshape it back into
the legacy RESP2 layout before the existing logic runs:

- RedisReply records IsMap (Resp3Type == Map) and exposes
  GetMapValueOrDefault; the existing flattening is preserved.
- SearchResponse.NormalizeReply and AggregationResult.NormalizeReply
  reshape map replies into the legacy [count, id, (score,) fields, ...]
  array (search) and [count, fields, ...] array (aggregation).
- RedisIndexInfoAttribute flattens RESP3's nested "flags" array so
  SORTABLE/NOSTEM/INDEXMISSING/INDEXEMPTY are detected under both
  protocols.
- RedisUriParser honors a "protocol" URI query arg and the
  REDIS_OM_PROTOCOL env var (resp2/resp3), giving users a workaround and
  enabling the full suite to run under RESP3.

Adds deterministic unit tests that feed synthetic RESP3 maps through the
search and aggregation parsers (CI runs RESP2 by default).

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: slorello89

src/Redis.OM/Aggregation/AggregationResult.cs

@@ -72,7 +72,7 @@ private AggregationResult(RedisReply res)
         /// <returns>A set of Aggregation Results.</returns>
         internal static IEnumerable<AggregationResult<T>> FromRedisResult(RedisReply res)
         {
-            var arr = res.ToArray();
+            var arr = AggregationResult.NormalizeReply(res);
             for (var i = 1; i < arr.Length; i++)
             {
                 yield return new AggregationResult<T>(arr[i]);
@@ -117,11 +117,40 @@ private AggregationResult(RedisReply res)
         /// <returns>an enumerable of results.</returns>
         public static IEnumerable<AggregationResult> FromRedisResult(RedisReply res)
         {
-            var arr = res.ToArray();
+            var arr = NormalizeReply(res);
             for (var i = 1; i < arr.Length; i++)
             {
                 yield return new AggregationResult(arr[i]);
             }
         }
+
+        /// <summary>
+        /// Normalizes an aggregation reply into the flat RESP2 layout the parsers expect. RESP2 replies
+        /// are returned unchanged; a RESP3 map reply (negotiated automatically by newer
+        /// StackExchange.Redis versions) is reshaped from its <c>total_results</c>/<c>results</c>
+        /// structure into the legacy <c>[count, fields, ...]</c> array, where each <c>fields</c> entry is
+        /// the result's <c>extra_attributes</c> map.
+        /// </summary>
+        /// <param name="res">The raw aggregation reply.</param>
+        /// <returns>The reply in flat RESP2 layout.</returns>
+        internal static RedisReply[] NormalizeReply(RedisReply res)
+        {
+            if (!res.IsMap)
+            {
+                return res.ToArray();
+            }
+
+            var flattened = new List<RedisReply> { res.GetMapValueOrDefault("total_results") ?? 0L };
+            var results = res.GetMapValueOrDefault("results");
+            if (results is not null)
+            {
+                foreach (var result in results.ToArray())
+                {
+                    flattened.Add(result.GetMapValueOrDefault("extra_attributes") ?? new RedisReply(Array.Empty<RedisReply>()));
+                }
+            }
+
+            return flattened.ToArray();
+        }
     }
 }

src/Redis.OM/RedisIndexInfo.cs

@@ -292,21 +292,36 @@ public RedisIndexInfoAttribute(RedisReply redisReply)
                         case "M": M = value; break;
                         case "ef_construction": EfConstruction = value; break;
                         case "WEIGHT": Weight = value; break;
-                        case "INDEXMISSING": IndexMissing = true; break;
-                        case "INDEXEMPTY": IndexEmpty = true; break;
                     }
                 }
 
-                if (responseArray.Any(x => ((string)x).Equals("NOSTEM", StringComparison.InvariantCultureIgnoreCase)))
+                // Boolean flags are emitted as trailing top-level tokens under RESP2, but grouped
+                // inside a nested "flags" array under RESP3. Flattening one level yields the leaf
+                // tokens for either layout so the flag detection below is protocol-agnostic.
+                var flagTokens = responseArray
+                    .SelectMany(x => x.ToArray())
+                    .Select(x => x.ToString(CultureInfo.InvariantCulture))
+                    .ToArray();
+
+                if (flagTokens.Any(x => x.Equals("NOSTEM", StringComparison.InvariantCultureIgnoreCase)))
                 {
                     NoStem = true;
                 }
 
-                if (responseArray.Select(x => x.ToString())
-                    .Any(x => x.Equals("SORTABLE", StringComparison.InvariantCultureIgnoreCase)))
+                if (flagTokens.Any(x => x.Equals("SORTABLE", StringComparison.InvariantCultureIgnoreCase)))
                 {
                     Sortable = true;
                 }
+
+                if (flagTokens.Any(x => x.Equals("INDEXMISSING", StringComparison.InvariantCultureIgnoreCase)))
+                {
+                    IndexMissing = true;
+                }
+
+                if (flagTokens.Any(x => x.Equals("INDEXEMPTY", StringComparison.InvariantCultureIgnoreCase)))
+                {
+                    IndexEmpty = true;
+                }
             }
 
             /// <summary>

src/Redis.OM/RedisReply.cs

@@ -44,6 +44,13 @@ public RedisReply(RedisResult result)
                     _values = ((RedisResult[])result!).Select(x => new RedisReply(x)).ToArray();
                     break;
             }
+
+            // When the connection negotiates RESP3, commands such as FT.SEARCH and FT.AGGREGATE
+            // reply with a map rather than the flat RESP2 array. SE.Redis collapses a map's
+            // Resp2Type to Array (the flattened, interleaved key/value pairs handled above), so the
+            // existing array-based parsing is preserved. We additionally record that the node was a
+            // map so response parsers can opt into the RESP3 shape via <see cref="IsMap"/>.
+            IsMap = result.Resp3Type == ResultType.Map;
         }
 
         /// <summary>
@@ -100,11 +107,30 @@ internal RedisReply(RedisReply[] values)
             _values = values;
         }
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="RedisReply"/> class representing a RESP3 map,
+        /// stored as a flattened, interleaved key/value array. Used to exercise the RESP3 parsing paths.
+        /// </summary>
+        /// <param name="values">the flattened key/value pairs.</param>
+        /// <param name="isMap">whether the reply represents a RESP3 map.</param>
+        internal RedisReply(RedisReply[] values, bool isMap)
+        {
+            _values = values;
+            IsMap = isMap;
+        }
+
         /// <summary>
         /// Gets a value indicating whether the result represents an error.
         /// </summary>
         public bool Error { get; }
 
+        /// <summary>
+        /// Gets a value indicating whether the reply was a RESP3 map (e.g. a RESP3 FT.SEARCH or
+        /// FT.AGGREGATE response). The underlying values are still exposed as the flattened,
+        /// interleaved key/value array via <see cref="ToArray"/>.
+        /// </summary>
+        internal bool IsMap { get; }
+
         /// <summary>
         /// implicitly converts the reply to a double.
         /// </summary>
@@ -508,5 +534,29 @@ public ulong ToUInt64(IFormatProvider provider)
 
             throw new InvalidCastException();
         }
+
+        /// <summary>
+        /// Looks up a value by key, treating this reply as a RESP3 map whose values are stored as a
+        /// flattened, interleaved key/value array.
+        /// </summary>
+        /// <param name="key">The map key to look up.</param>
+        /// <returns>The value associated with <paramref name="key"/>, or <c>null</c> if absent.</returns>
+        internal RedisReply? GetMapValueOrDefault(string key)
+        {
+            if (_values is null)
+            {
+                return null;
+            }
+
+            for (var i = 0; i + 1 < _values.Length; i += 2)
+            {
+                if ((string)_values[i] == key)
+                {
+                    return _values[i + 1];
+                }
+            }
+
+            return null;
+        }
     }
 }

src/Redis.OM/RedisUriParser.cs

@@ -26,19 +26,60 @@ internal static ConfigurationOptions ParseConfigFromUri(string uriString)
             if (string.IsNullOrEmpty(uriString))
             {
                 options.EndPoints.Add("localhost:6379");
+                ParseProtocol(options, null);
                 return options;
             }
 
             var uri = new Uri(uriString);
             ParseHost(options, uri);
             ParseUserInfo(options, uri);
             ParseQueryArguments(options, uri);
+            ParseProtocol(options, uri);
             ParseDefaultDatabase(options, uri);
             options.Ssl = uri.Scheme == "rediss";
             options.AbortOnConnectFail = false;
             return options;
         }
 
+        /// <summary>
+        /// Resolves the RESP protocol to negotiate. An explicit <c>protocol</c> query argument
+        /// (<c>resp2</c>/<c>resp3</c> or <c>2</c>/<c>3</c>) takes precedence; otherwise the
+        /// <c>REDIS_OM_PROTOCOL</c> environment variable is used as a fallback default. When neither is
+        /// supplied the StackExchange.Redis default is left untouched.
+        /// </summary>
+        /// <param name="options">The configuration options to populate.</param>
+        /// <param name="uri">The parsed URI, or <c>null</c> when none was supplied.</param>
+        private static void ParseProtocol(ConfigurationOptions options, Uri? uri)
+        {
+            string? requested = null;
+            if (uri is not null && !string.IsNullOrEmpty(uri.Query))
+            {
+                requested = ParseQuery(uri.Query.Substring(1))
+                    .Where(x => x.Key.ToLower() == "protocol")
+                    .Select(x => x.Value)
+                    .FirstOrDefault();
+            }
+
+            requested ??= Environment.GetEnvironmentVariable("REDIS_OM_PROTOCOL");
+
+            if (string.IsNullOrEmpty(requested))
+            {
+                return;
+            }
+
+            switch (requested!.Trim().ToLowerInvariant())
+            {
+                case "2":
+                case "resp2":
+                    options.Protocol = RedisProtocol.Resp2;
+                    break;
+                case "3":
+                case "resp3":
+                    options.Protocol = RedisProtocol.Resp3;
+                    break;
+            }
+        }
+
         private static void ParseDefaultDatabase(ConfigurationOptions options, Uri uri)
         {
             if (string.IsNullOrEmpty(uri.AbsolutePath))

src/Redis.OM/Searching/SearchResponse.cs

@@ -15,7 +15,7 @@ public class SearchResponse
         /// <param name="val">The redis response.</param>
         public SearchResponse(RedisReply val)
         {
-            var vals = val.ToArray();
+            var vals = NormalizeReply(val);
             DocumentCount = vals[0];
             Documents = new Dictionary<string, IDictionary<string, string>>();
             Scores = new Dictionary<string, double>();
@@ -80,6 +80,44 @@ public IDictionary<string, T> DocumentsAs<T>()
             return dict;
         }
 
+        /// <summary>
+        /// Normalizes a search reply into the flat RESP2 layout the parsers expect. RESP2 replies are
+        /// returned unchanged; a RESP3 map reply (negotiated automatically by newer StackExchange.Redis
+        /// versions) is reshaped from its <c>total_results</c>/<c>results</c> structure into the legacy
+        /// <c>[count, id, (score,) fields, ...]</c> array.
+        /// </summary>
+        /// <param name="val">The raw search reply.</param>
+        /// <returns>The reply in flat RESP2 layout.</returns>
+        internal static RedisReply[] NormalizeReply(RedisReply val)
+        {
+            if (!val.IsMap)
+            {
+                return val.ToArray();
+            }
+
+            var flattened = new List<RedisReply> { val.GetMapValueOrDefault("total_results") ?? 0L };
+            var results = val.GetMapValueOrDefault("results");
+            if (results is not null)
+            {
+                foreach (var result in results.ToArray())
+                {
+                    flattened.Add(result.GetMapValueOrDefault("id") ?? string.Empty);
+
+                    // WITHSCORES surfaces the score as a scalar map entry; the existing parser treats it
+                    // as the metadata sitting between the id and the field payload.
+                    var score = result.GetMapValueOrDefault("score");
+                    if (score is not null)
+                    {
+                        flattened.Add(score);
+                    }
+
+                    flattened.Add(result.GetMapValueOrDefault("extra_attributes") ?? new RedisReply(Array.Empty<RedisReply>()));
+                }
+            }
+
+            return flattened.ToArray();
+        }
+
         /// <summary>
         /// Walks forward over scalar metadata entries (e.g. the score emitted by WITHSCORES) that sit between a
         /// document's id and its field payload, returning the index of the field payload.
@@ -154,7 +192,7 @@ public SearchResponse(RedisReply val)
             }
             else
             {
-                var vals = val.ToArray();
+                var vals = SearchResponse.NormalizeReply(val);
                 if (vals.Length == 1)
                 {
                     var str = vals[0].ToString();
@@ -248,7 +286,7 @@ private SearchResponse()
 
         private static SearchResponse<T> PrimitiveSearchResponse(RedisReply redisReply)
         {
-            var arr = redisReply.ToArray();
+            var arr = SearchResponse.NormalizeReply(redisReply);
             var response = new SearchResponse<T>();
             response.DocumentCount = arr[0];
             for (var i = 1; i < arr.Count();)