Merge branch 'main' of https://github.com/cajuncoding/Flurl.Http.GraphQL

# Conflicts:
#	FlurlGraphQL.Querying/GraphQL/GraphQLQueryResults.cs

Author: cajuncoding

FlurlGraphQL.Querying/Flurl/FlurlGraphQLRequest.cs

@@ -1,17 +1,28 @@
 using System;
 using System.Collections.Generic;
 using System.Collections.ObjectModel;
+using System.Linq;
 using System.Net;
 using System.Net.Http;
 using System.Threading;
 using System.Threading.Tasks;
 using Flurl;
 using Flurl.Http;
 using Flurl.Http.Configuration;
+using Flurl.Http.Content;
 using Flurl.Util;
+using Newtonsoft.Json;
+using NullValueHandling = Flurl.NullValueHandling;
 
 namespace FlurlGraphQL.Querying
 {
+    public enum GraphQLQueryType
+    {
+        Undefined,
+        Query,
+        PersistedQuery
+    };
+
     public class FlurlGraphQLRequest : IFlurlGraphQLRequest
     {
         protected IFlurlRequest BaseFlurlRequest { get; set; }
@@ -20,6 +31,9 @@ internal FlurlGraphQLRequest(IFlurlRequest baseRequest)
             BaseFlurlRequest = baseRequest.AssertArgIsNotNull(nameof(baseRequest));
         }
 
+        public GraphQLQueryType GraphQLQueryType { get; protected set; }
+
+
         #region GraphQL Variables
 
         protected Dictionary<string, object> GraphQLVariablesInternal { get; set; } = new Dictionary<string, object>();
@@ -93,62 +107,194 @@ public IFlurlGraphQLRequest SetContextItems(IEnumerable<(string Key, object Valu
 
         #endregion
 
-        #region GraphQL Query Param/Body
+        #region WithGraphQLQuery()
 
         public string GraphQLQuery { get; protected set; } = null;
 
         public IFlurlGraphQLRequest WithGraphQLQuery(string query, NullValueHandling nullValueHandling = NullValueHandling.Remove)
         {
             if (query != null || nullValueHandling == NullValueHandling.Remove)
+            {
+                //NOTE: By design, Persisted Queries and normal Queries are mutually exclusive so only one will be populated at a time,
+                //          we enforce this by clearing them both when a new item is being set...
+                ClearGraphQLQuery();
                 GraphQLQuery = query;
+                GraphQLQueryType = GraphQLQueryType.Query;
+            }
 
             return this;
         }
 
+        #endregion
+
+        #region WithGraphQLPersistedQuery()
+
+        public IFlurlGraphQLRequest WithGraphQLPersistedQuery(string id, NullValueHandling nullValueHandling = NullValueHandling.Remove)
+        {
+            if (id != null || nullValueHandling == NullValueHandling.Remove)
+            {
+                //NOTE: By design, Persisted Queries and normal Queries are mutually exclusive so only one will be populated at a time,
+                //          we enforce this by clearing them both when a new item is being set...
+                ClearGraphQLQuery();
+                GraphQLQuery = id;
+                GraphQLQueryType = GraphQLQueryType.PersistedQuery;
+            }
+
+            return this;
+        }
+
+        #endregion
+
+        #region ClearGraphQLQuery(), Clone()
+
         public IFlurlGraphQLRequest ClearGraphQLQuery()
         {
             GraphQLQuery = null;
+            GraphQLQueryType = GraphQLQueryType.Undefined;
             return this;
         }
 
         public IFlurlGraphQLRequest Clone()
         {
-            return new FlurlGraphQLRequest(this.BaseFlurlRequest)
-                .WithGraphQLQuery(this.GraphQLQuery)
+            var clone = (IFlurlGraphQLRequest)new FlurlGraphQLRequest(this.BaseFlurlRequest);
+
+            switch (this.GraphQLQueryType)
+            {
+                case GraphQLQueryType.PersistedQuery:
+                    clone = clone.WithGraphQLPersistedQuery(this.GraphQLQuery);
+                    break;
+                case GraphQLQueryType.Query:
+                    clone = clone.WithGraphQLQuery(this.GraphQLQuery);
+                    break;
+                //NOTE: It's ok to Clone a GraphQL query that you may be initialized later...
+                //default:
+                //    throw new ArgumentOutOfRangeException(nameof(GraphQLQueryType), "The GraphQL Query Type is undefined or invalid.");
+            }
+
+            clone
                 .SetGraphQLVariables(this.GraphQLVariablesInternal)
                 .SetContextItems(this.ContextBagInternal);
+
+            return clone;
         }
 
         #endregion
 
         #region GraphQL Query Execution with Server
 
-        public async Task<IFlurlGraphQLResponse> PostGraphQLQueryAsync<TVariables>(TVariables variables, CancellationToken cancellationToken = default, NullValueHandling nullValueHandling = NullValueHandling.Remove)
-            where TVariables : class
+        /// <summary>
+        /// Execute the GraphQL query with the Server using POST request (Strongly Recommended vs Get).
+        /// </summary>
+        /// <typeparam name="TVariables"></typeparam>
+        /// <param name="variables"></param>
+        /// <param name="cancellationToken"></param>
+        /// <param name="nullValueHandling"></param>
+        /// <returns></returns>
+        /// <exception cref="InvalidOperationException"></exception>
+        /// <exception cref="FlurlGraphQLException"></exception>
+        public async Task<IFlurlGraphQLResponse> PostGraphQLQueryAsync<TVariables>(
+            TVariables variables, 
+            CancellationToken cancellationToken = default, 
+            NullValueHandling nullValueHandling = NullValueHandling.Remove
+        ) where TVariables : class
         {
-            var graphqlQuery = this.GraphQLQuery;
+            //NOTE: By design, Persisted Queries and normal Queries are mutually exclusive so only one will be populated at a time...
+            var graphqlQueryType = this.GraphQLQueryType;
+            var graphqlQueryOrId = this.GraphQLQuery;
 
             //Get the GraphQL Query and remove it from the QueryString...
-            if (string.IsNullOrWhiteSpace(graphqlQuery))
-                throw new InvalidOperationException($"The GraphQL Query is undefined; use {nameof(WithGraphQLQuery)}() to specify the body of the query.");
+            if (graphqlQueryType == GraphQLQueryType.Undefined || string.IsNullOrWhiteSpace(graphqlQueryOrId))
+                throw new InvalidOperationException($"The GraphQL Query is undefined; use {nameof(WithGraphQLQuery)}() or {nameof(WithGraphQLPersistedQuery)}() to specify the query.");
 
             //Process any additional variables that may have been provided directly to this call...
             //NOTE: None of these will have used our prefix convention...
             if (variables != null)
                 this.SetGraphQLVariables(variables, nullValueHandling);
 
-            //Execute the Query with the GraphQL Server...
-            var graphqlPayload = new FlurlGraphQLRequestPayload(graphqlQuery, this.GraphQLVariablesInternal);
+            //Execute the Request with shared Exception handling...
+            return await ExecuteRequestWithExceptionHandling(async () =>
+            {
+                //Execute the Query with the GraphQL Server...
+                var graphqlPayload = new FlurlGraphQLRequestPayload(graphqlQueryType, graphqlQueryOrId, this.GraphQLVariablesInternal);
+                var jsonPayload = SerializeToJsonWithOptionalGraphQLSerializerSettings(graphqlPayload);
+
+                //Since we have our own GraphQL Serializer Settings, our payload is already serialized so we can just send it!
+                //NOTE: Borrowed directly from the Flurl.PostJsonAsync() method but 
+                var response = await this.SendAsync(
+                    HttpMethod.Post,
+                    new CapturedJsonContent(jsonPayload),
+                    cancellationToken,
+                    completionOption: HttpCompletionOption.ResponseContentRead
+                ).ConfigureAwait(false);
 
-            try
+                return new FlurlGraphQLResponse(response, this);
+
+            }).ConfigureAwait(false);
+        }
+
+        /// <summary>
+        /// STRONGLY DISCOURAGED -- Execute the GraphQL query with the Server using GET request.
+        /// This is Strongly Discouraged as POST requests are much more robust. But this is provided for edge cases where GET requests must be used.
+        /// </summary>
+        /// <typeparam name="TVariables"></typeparam>
+        /// <param name="variables"></param>
+        /// <param name="cancellationToken"></param>
+        /// <param name="nullValueHandling"></param>
+        /// <returns></returns>
+        /// <exception cref="InvalidOperationException"></exception>
+        /// <exception cref="FlurlGraphQLException"></exception>
+        public async Task<IFlurlGraphQLResponse> GetGraphQLQueryAsync<TVariables>(
+            TVariables variables,
+            CancellationToken cancellationToken = default,
+            NullValueHandling nullValueHandling = NullValueHandling.Remove
+        ) where TVariables : class
+        {
+            //NOTE: By design, Persisted Queries and normal Queries are mutually exclusive so only one will be populated at a time...
+            var graphqlQueryType = this.GraphQLQueryType;
+            var graphqlQueryOrId = this.GraphQLQuery;
+
+            //Get the GraphQL Query and remove it from the QueryString...
+            if (graphqlQueryType == GraphQLQueryType.Undefined || string.IsNullOrWhiteSpace(graphqlQueryOrId))
+                throw new InvalidOperationException($"The GraphQL Query is undefined; use {nameof(WithGraphQLQuery)}() or {nameof(WithGraphQLPersistedQuery)}() to specify the query.");
+
+            //Process any additional variables that may have been provided directly to this call...
+            //NOTE: None of these will have used our prefix convention...
+            if (variables != null)
+                this.SetGraphQLVariables(variables, nullValueHandling);
+
+            //Execute the Request with shared Exception handling...
+            return await ExecuteRequestWithExceptionHandling(async () =>
             {
-                var response = await this.PostJsonAsync(
-                    graphqlPayload,
+                switch (this.GraphQLQueryType)
+                {
+                    case GraphQLQueryType.Query: this.SetQueryParam("query", this.GraphQLQuery); break;
+                    case GraphQLQueryType.PersistedQuery: this.SetQueryParam("id", this.GraphQLQuery); break;
+                    default: throw new ArgumentOutOfRangeException(nameof(graphqlQueryType), $"GraphQL Query Type [{graphqlQueryType}] cannot be initialized.");
+                }
+
+                if (this.GraphQLVariablesInternal?.Any() ?? false)
+                {
+                    var variablesJson = SerializeToJsonWithOptionalGraphQLSerializerSettings(this.GraphQLVariablesInternal);
+                    this.SetQueryParam("variables", variablesJson);
+                }
+
+                var response = await this.GetAsync(
                     cancellationToken,
                     completionOption: HttpCompletionOption.ResponseContentRead
                 ).ConfigureAwait(false);
 
                 return new FlurlGraphQLResponse(response, this);
+
+            }).ConfigureAwait(false);
+        }
+
+        protected async Task<FlurlGraphQLResponse> ExecuteRequestWithExceptionHandling(Func<Task<FlurlGraphQLResponse>> sendRequestFunc)
+        {
+            sendRequestFunc.AssertArgIsNotNull(nameof(sendRequestFunc));
+
+            try
+            {
+                return await sendRequestFunc().ConfigureAwait(false);
             }
             catch (FlurlHttpException httpException)
             {
@@ -159,13 +305,27 @@ public async Task<IFlurlGraphQLResponse> PostGraphQLQueryAsync<TVariables>(TVari
                     throw new FlurlGraphQLException(
                         $"[{(int)HttpStatusCode.BadRequest}-{HttpStatusCode.BadRequest}] The GraphQL server returned a bad request response for the query."
                         + " This is likely caused by a malformed, or non-parsable query; validate the query syntax, operation name, arguments, etc."
-                        + " to ensure that the query is valid.", graphqlQuery, errorContent, httpStatusCode, httpException
+                        + " to ensure that the query is valid.", this.GraphQLQuery, errorContent, httpStatusCode, httpException
                     );
                 else
                     throw;
             }
         }
 
+        protected string SerializeToJsonWithOptionalGraphQLSerializerSettings(object obj)
+        {
+            var jsonSerializerSettings = ContextBag?.TryGetValue(nameof(JsonSerializerSettings), out var serializerSettings) ?? false
+                ? serializerSettings as JsonSerializerSettings
+                : null;
+
+            //Ensure that all json parsing uses a Serializer with the GraphQL Contract Resolver...
+            //NOTE: We still support normal Serializer Default settings via Newtonsoft framework!
+            //var jsonSerializer = JsonSerializer.CreateDefault(jsonSerializerSettings);
+            var json = JsonConvert.SerializeObject(obj, jsonSerializerSettings);
+            return json;
+        }
+
+
         #endregion
 
         #region IFlurlRequest Interface Implementations

FlurlGraphQL.Querying/Flurl/FlurlGraphQLRequestExtensions.cs

@@ -20,11 +20,48 @@ public static class FlurlGraphQLRequestExtensions
 
         public static IFlurlGraphQLRequest ToGraphQLRequest(this IFlurlRequest request)
             => request is FlurlGraphQLRequest graphqlRequest ? graphqlRequest : new FlurlGraphQLRequest(request);
-        
+
+        #endregion
+
+        #region WithGraphQLPersistedQuery()
+
+        /// <summary>
+        /// Initialize the query body for a GraphQL query request.
+        /// </summary>
+        /// <param name="url"></param>
+        /// <param name="query"></param>
+        /// <returns>Returns an IFlurlGraphQLRequest for ready to chain for further initialization or execution.</returns>
+        public static IFlurlGraphQLRequest WithGraphQLPersistedQuery(this string url, string id) => ToGraphQLRequest(url).WithGraphQLPersistedQuery(id);
+
+        /// <summary>
+        /// Initialize the query body for a GraphQL query request.
+        /// </summary>
+        /// <param name="url"></param>
+        /// <param name="query"></param>
+        /// <returns>Returns an IFlurlGraphQLRequest for ready to chain for further initialization or execution.</returns>
+        public static IFlurlGraphQLRequest WithGraphQLPersistedQuery(this Uri url, string id) => ToGraphQLRequest(url).WithGraphQLPersistedQuery(id);
+
+        /// <summary>
+        /// Initialize the query body for a GraphQL query request.
+        /// </summary>
+        /// <param name="url"></param>
+        /// <param name="query"></param>
+        /// <returns>Returns an IFlurlGraphQLRequest for ready to chain for further initialization or execution.</returns>
+        public static IFlurlGraphQLRequest WithGraphQLPersistedQuery(this Url url, string id) => ToGraphQLRequest(url).WithGraphQLPersistedQuery(id);
+
+        /// <summary>
+        /// Initialize the query body for a GraphQL query request.
+        /// </summary>
+        /// <param name="request"></param>
+        /// <param name="query"></param>
+        /// <returns>Returns an IFlurlGraphQLRequest for ready to chain for further initialization or execution.</returns>
+        public static IFlurlGraphQLRequest WithGraphQLPersistedQuery(this IFlurlRequest request, string id) => request.ToGraphQLRequest().WithGraphQLPersistedQuery(id);
+
+
         #endregion
-        
+
         #region WithGraphQLQuery()...
-        
+
         /// <summary>
         /// Initialize the query body for a GraphQL query request.
         /// </summary>
@@ -195,7 +232,7 @@ public static IFlurlGraphQLRequest SetGraphQLNewtonsoftJsonSerializerSettings(th
         #region PostGraphQLQueryAsnc()...
 
         /// <summary>
-        /// Execute the GraphQL Query, along with initialized variables, with the GraphQL Server specified by the original Url.
+        /// Execute the GraphQL Query as a POST request (Strongly Recommended vs GET), along with initialized variables, with the GraphQL Server specified by the original Url.
         /// If no GraphQL Query has been specified via WithGraphQLQuery() then an InvalidOperationException will be thrown; otherwise
         /// any other errors returned by the GraphQL server will result in a FlurlGraphQLException being thrown containing all relevant details about the errors.
         /// </summary>
@@ -205,6 +242,19 @@ public static IFlurlGraphQLRequest SetGraphQLNewtonsoftJsonSerializerSettings(th
         public static Task<IFlurlGraphQLResponse> PostGraphQLQueryAsync(this IFlurlRequest request, CancellationToken cancellationToken = default)
             => request.ToGraphQLRequest().PostGraphQLQueryAsync<object>(null, cancellationToken: cancellationToken);
 
+        /// <summary>
+        /// STRONGLY DISCOURAGED -- Execute the GraphQL Query as a GET request, along with initialized variables, with the GraphQL Server specified by the original Url.
+        /// This is Strongly Discouraged as POST requests are much more robust. But this is provided for edge cases where GET requests must be used.
+        /// If no GraphQL Query has been specified via WithGraphQLQuery() then an InvalidOperationException will be thrown; otherwise
+        /// any other errors returned by the GraphQL server will result in a FlurlGraphQLException being thrown containing all relevant details about the errors.
+        /// </summary>
+        /// <param name="request"></param>
+        /// <param name="cancellationToken"></param>
+        /// <returns>Returns an async IFlurlGraphQLResponse ready to be processed by various ReceiveGraphQL*() methods to handle the results based on the type of query.</returns>
+        public static Task<IFlurlGraphQLResponse> GetGraphQLQueryAsync(this IFlurlRequest request, CancellationToken cancellationToken = default)
+            => request.ToGraphQLRequest().GetGraphQLQueryAsync<object>(null, cancellationToken: cancellationToken);
+
+
         #endregion
     }
 }

FlurlGraphQL.Querying/Flurl/FlurlGraphQLResponseExtensions.Internal.cs

@@ -212,6 +212,15 @@ internal static IGraphQLQueryResults<TEntityResult> ParseJsonToGraphQLResultsInt
             var jsonSerializer = JsonSerializer.CreateDefault(jsonSerializerSettings);
             jsonSerializer.Converters.Add(new GraphQLPageResultsToICollectionConverter());
 
+            return ParseJsonToGraphQLResultsWithJsonSerializerInternal<TEntityResult>(json, jsonSerializer);
+        }
+
+        internal static IGraphQLQueryResults<TEntityResult> ParseJsonToGraphQLResultsWithJsonSerializerInternal<TEntityResult>(this JToken json, JsonSerializer jsonSerializer)
+            where TEntityResult : class
+        {
+            if (json == null)
+                return new GraphQLQueryResults<TEntityResult>();
+
             //Dynamically parse the data from the results...
             //NOTE: We process PageInfo as Cursor Paging as the Default (because it's strongly encouraged by GraphQL.org
             //          & Offset Paging model is a subset of Cursor Paging (less flexible).

FlurlGraphQL.Querying/Flurl/FlurlGraphQLResponseExtensions.cs

@@ -149,7 +149,7 @@ public static async Task<IList<IGraphQLConnectionResults<TResult>>> ReceiveAllGr
         /// See: https://relay.dev/graphql/connections.htm
         /// </summary>
         /// <typeparam name="TResult"></typeparam>
-        /// <param name="responseTask"></param>
+        /// <param name="response"></param>
         /// <param name="queryOperationName"></param>
         /// <param name="cancellationToken"></param>
         /// <returns>Returns a List of ALL IGraphQLQueryConnectionResult set of typed results along with paging information returned by the query.</returns>