API.Utilities.cs

Go to the documentation of this file.

using System;
using System.Collections.Concurrent;
using System.Collections.Generic;
using System.Diagnostics;
using System.Globalization;
using System.Linq;
using System.Net;
using System.Reflection;
using System.Text;
using System.Threading;
using System.Threading.Tasks;
 
using AnalyzeRe.APITypes;
using AnalyzeRe.Rest;
using AnalyzeRe.Utilities;
using Newtonsoft.Json;
using RestSharp;
 
namespace AnalyzeRe
{
    public static partial class API
    {
        internal const string DebugTimeFormat = @"yyyy-MM-dd HH:mm:ss.FFFF";
        private const NumberStyles DoubleParseStyle = NumberStyles.AllowDecimalPoint;
        private const NumberStyles IntParseStyle = NumberStyles.None;
        private static readonly CultureInfo ParseCulture = CultureInfo.InvariantCulture;
 
        #region Public Utilities
        public static bool IsAReServerActive(string checkServerURL, int? timeout = null)
        {
            try
            {
                RestClient testClient = GetRestClient(new Uri(checkServerURL));
                RestRequest testRequest = new RestRequest(Method.OPTIONS)
                {
                    Timeout = timeout ?? DefaultRequestTimeout
                };
                IRestResponse response = testClient.Execute(testRequest);
                // If the request gets through and the server header identifies the response
                // as coming from an Analyze Re API server, return true.
                if (response.ResponseStatus == ResponseStatus.Completed &&
                    (response.Server == AnalyzeReServerIdentity ||
                    response.Headers.Any(h => h.Name == "ARE-Server")))
                {
                    return true;
                }
            }
            // ReSharper disable once EmptyGeneralCatchClause (any error means URL is not valid)
            catch { }
            return false;
        }
 
        #region Polling
        public static TResponse PollUntil<TResponse>(
            Func<TResponse> request,
            Func<TResponse, bool> isPollingComplete,
            AnalyzeRe.PollingOptions pollingOptions = null)
        {
            pollingOptions = pollingOptions ?? AnalyzeRe.PollingOptions.Default;
            int count = 0, sleep_ms = 0, elapsed_ms, remaining_ms;
            DateTime start = DateTime.UtcNow;
            bool completed;
            TResponse response;
 
            do
            {
                if (pollingOptions.CancellationToken?.IsCancellationRequested ?? false)
                    throw new TaskCanceledException();
                if (sleep_ms != 0)
                    Thread.Sleep(sleep_ms);
                // Invoke the supplied methods
                response = request();
                completed = isPollingComplete(response);
                // Increment the various counters and prepare the next sleep time.
                count++;
                elapsed_ms = (int)(DateTime.UtcNow - start).TotalMilliseconds;
                remaining_ms = pollingOptions.MaxPollTotalTime - elapsed_ms;
                sleep_ms = pollingOptions.GetNextPollTime(sleep_ms, elapsed_ms);
                // Loop until we time out or the status is finalized
            } while (!completed && remaining_ms > 0);
 
            if (!completed)
                throw new NotWaitingException(
                    $"The request is still not complete after {elapsed_ms / 1000d} seconds, which " +
                    $"exceeds the timeout of {pollingOptions.MaxPollTotalTime / 1000d}s.",
                    elapsed_ms / 1000d, maxWaitTime: pollingOptions.MaxPollTotalTime / 1000d,
                    restResponse: response as IRestResponse);
 
            Debug.WriteLine($"Polling completed after {count} attempts (took {elapsed_ms / 1000d} seconds).");
            return response;
        }
 
        public static void PollUntil(Func<bool> request, AnalyzeRe.PollingOptions pollingOptions = null)
            => PollUntil(request, result => result, pollingOptions);
 
        public static T PollUntilReady<T>(
            Func<T> functionThatMight503,
            AnalyzeRe.PollingOptions pollingOptions = null)
        {
            double? suggestedWaitSeconds = null;
            int? queuePosition = null;
            Exception handled = null;
            try
            {
                object PollingRequest()
                {
                    try
                    {
                        suggestedWaitSeconds = null;
                        queuePosition = null;
                        T response = functionThatMight503();
                        if (response == null)
                            throw new Exception("The server replied successfully, but the response was null.");
                        return response;
                    }
                    // APIRequestException is expected so long as the result is not yet ready.
                    // TODO: Encapsulate this exception parsing logic so anyone can benefit
                    catch (APIRequestException ex)
                    {
                        if (ex.RestResponse?.StatusCode != HttpStatusCode.ServiceUnavailable)
                            throw;
 
                        // Parse the retryAfter header out of the response.
                        Parameter retryAfter = ex.RestResponse.Headers.FirstOrDefault(
                            header => header.Name.Equals("Retry-After", StringComparison.OrdinalIgnoreCase));
                        if (retryAfter == null)
                            suggestedWaitSeconds = null;
                        else if (Double.TryParse(retryAfter.Value.ToString(),
                                 DoubleParseStyle, ParseCulture, out double retryAfterParsed))
                            suggestedWaitSeconds = retryAfterParsed;
                        else
                            throw new APIRequestException("The server provided a Retry-After header, " +
                                $"but it could not be parsed: {retryAfter.Value}",
                                ex, ex.RestResponse, ex.ServerError);
 
                        // Parse the queuePosition header out of the response.
                        Parameter queueHeader = ex.RestResponse.Headers.FirstOrDefault(
                            header => header.Name.Equals("Queue-Position", StringComparison.OrdinalIgnoreCase));
                        if (queueHeader == null)
                            queuePosition = null;
                        else if (Int32.TryParse(queueHeader.Value.ToString(),
                                IntParseStyle, ParseCulture, out int queuePositionParsed))
                            queuePosition = queuePositionParsed;
                        else
                            throw new APIRequestException("The server provided a Queue-Position header, " +
                                $"but it could not be parsed: {queueHeader.Value}",
                                ex, ex.RestResponse, ex.ServerError);
 
                        handled = ex;
                    }
                    return null;
                }
 
                return (T)PollUntil(pollingOptions: pollingOptions,
                    isPollingComplete: res => res != null,
                    request: PollingRequest);
            }
            // Intercept the NotWaitingException and re-raise with a more meaningful message.
            catch (NotWaitingException ex)
            {
                string suffix = ((ex.MaxWaitTime ?? 0d) <= 0d ? "" :
                        $"The maximum wait time of {ex.MaxWaitTime} seconds has been exceeded. ") +
                    "Please try again later.";
                string message = null;
                // If the server is returning a queue position or ETA, include it in the message
                if (queuePosition != null)
                    message += $"Simulation is queued at position {queuePosition}. ";
                if (suggestedWaitSeconds != null)
                    message += $"Server suggests retrying after {suggestedWaitSeconds} seconds. ";
                // Raise a new NotWaitingException with a custom message
                throw new NotWaitingException(message + suffix,
                    ex.TimeWaited,
                    retryTime: suggestedWaitSeconds,
                    queuePosition: queuePosition,
                    maxWaitTime: ex.MaxWaitTime,
                    innerException: handled,
                    restResponse: handled is APIRequestException requestEx ?
                        requestEx.RestResponse : ex.RestResponse);
            }
        }
        #endregion Polling
 
        #region Get Collection Name
        #region Method Overloads
        public static string GetCollectionName<T>() where T : IAPIResource
        {
            return GetCollectionName<T>(out Type _);
        }
        public static string GetCollectionName<T>(out Type declaringClassType) where T : IAPIResource
        {
            return GetCollectionName(typeof(T), out declaringClassType);
        }
 
        public static string GetCollectionName(Type requestType)
        {
            return GetCollectionName(requestType, out Type _);
        }
        #endregion Method Overloads
 
        private static readonly ConcurrentDictionary<Type, Tuple<Type, string>>
            CollectionNameCache = new ConcurrentDictionary<Type, Tuple<Type, string>>();
 
        public static string GetCollectionName(Type requestType, out Type declaringClassType,
            bool suppress_throw = false)
        {
            // Standard resource types as a rule have this static field defined in each resource class.
            const string collectionNameField = "CLASS_COLLECTION_NAME";
            // Any class that implements IAPIResourceView must have this public gettable property
            // that returns the resource collection name
            const string interfaceCollectionProperty = "collection_name";
 
            // Check if we've already looked up the collection name for this type
            if (CollectionNameCache.TryGetValue(requestType, out Tuple<Type, string> cachedEntry))
            {
                // If we have a cached entry that is null, it means we've previously gone through
                // the work of determining that this is an unsupported type.
                // Reuse that knowledge if suppress_throw is set and return null, otherwise
                // if the value is null, go through the work again to throw a meaningful exception.
                if (cachedEntry != null || suppress_throw)
                {
                    declaringClassType = cachedEntry?.Item1;
                    return cachedEntry?.Item2;
                }
            }
            // If the entry is not in the cache, we must compute it.
 
            // First, throw an error if this isn't a supported type (only resources have collections)
            if (!typeof(IAPIResource).IsAssignableFrom(requestType))
            {
                if (!suppress_throw)
                    throw new ArgumentException($"{requestType.NiceTypeName()} " +
                        "does not derive from IAPIResource.");
                declaringClassType = null;
                return null;
            }
 
            // Binding flags combinations that get used a few times
            const BindingFlags publicStaticInherited =
                BindingFlags.FlattenHierarchy | BindingFlags.Public | BindingFlags.Static;
            const BindingFlags publicInstanceInherited =
                BindingFlags.FlattenHierarchy | BindingFlags.Public | BindingFlags.Instance;
 
            string collectionName = null;
            // For a start, assume the requestType is the base resource type
            declaringClassType = requestType;
 
            // Hack: If the declaring type is generic, the field is re-defined in each generic type.
            // We need to find the base covariant type which defines this.
            if (declaringClassType.IsGenericType)
            {
                declaringClassType = declaringClassType.GetGenericTypeDefinition();
                // Assume there's only one parameter and fill in from the type constraint.
                declaringClassType = declaringClassType.MakeGenericTypeFast(
                    declaringClassType.GetGenericArguments()[0].GetGenericParameterConstraints()[0]);
            }
 
            // Most classes define a public static CLASS_COLLECTION_NAME field,
            // which is simplest to use, but this is not a necessary interface member.
            FieldInfo field = declaringClassType.GetField(collectionNameField, publicStaticInherited);
            if (field != null)
            {
                declaringClassType = field.DeclaringType;
                collectionName = (string)field.GetValue(null);
            }
            // If they didn't follow the CLASS_COLLECTION_NAME convention, then an instance of the type
            // must at least have a collection_name property, according to the IApiResource interface
            else if (!declaringClassType.IsAbstract && !declaringClassType.IsInterface)
            {
                // See if we can get the collection name by creating an instance of the declaring class type
                try
                {
                    IAPIResource instance = (IAPIResource)Activator.CreateInstance(requestType);
                    PropertyInfo collectionNamePropertyInfo =
                        requestType.GetProperty(interfaceCollectionProperty, publicInstanceInherited);
                    // This should never happen if this requestType is an IAPIResource
                    if (collectionNamePropertyInfo == null)
                        throw new Exception("The type " + requestType.NiceTypeName() +
                            " does not define or inherit a collection_name property.");
                    // Get the base class that actually declared this property
                    declaringClassType = collectionNamePropertyInfo.DeclaringType;
                    collectionName = (string)collectionNamePropertyInfo.GetValue(instance, null);
                }
                catch { collectionName = null; }
            }
 
            // If we don't have collectionName yet we have a non-instantiable base class or
            // interface type on our hands. We can try to search for a derived type that does
            // implement one of these properties, but it might break covariance.
            if (collectionName == null)
            {
                // Hack: The IAPIResource interface does enforce the existence of a collection_name
                //       instance property, it just can't declare it, so we'll have to get an
                //       instance of this type (or a sub-type) to get the collection name, but this
                //       won't necessarily be the declaring type.
                IEnumerable<Type> subTypes = TypeResolver.GetAllInstantiableSubtypes(requestType);
 
                // Try to get the collection name from each of these instantiable types.
                // If all that supply the collection name are in agreement about the collection
                // name and declaringClassType, then return those as the result.
                foreach (Type instantiable in subTypes)
                {
                    string tempCollectionName = null;
                    Type tempDeclaringClassType = null;
                    try
                    {
                        tempCollectionName = GetCollectionName(instantiable, out tempDeclaringClassType);
                    }
                    // ReSharper disable once EmptyGeneralCatchClause
                    // (Don't care about errors in recursive calls.)
                    catch { }
                    // If this instantiable type didn't have this property, continue
                    if (tempCollectionName == null) continue;
                    // If this is the first result we've received, store the results
                    if (collectionName == null)
                    {
                        collectionName = tempCollectionName;
                        declaringClassType = tempDeclaringClassType;
                    }
                    // Otherwise, ensure the new result agrees with the prior results.
                    // This verifies that derived objects report the same collection name
                    if (collectionName != tempCollectionName)
                    {
                        // Cache the null result and either raise an error or allow null to be returned
                        CollectionNameCache.TryAdd(requestType, null);
                        if (!suppress_throw)
                            throw new ArgumentException("Invalid type " + requestType.NiceTypeName() +
                                ". Type can be linked to more than one resource (" + collectionName +
                                ", " + tempCollectionName + ")");
                        declaringClassType = null;
                        return null;
                    }
                    // This verifies that all derived objects report the base same class
                    if (declaringClassType != tempDeclaringClassType)
                    {
                        CollectionNameCache.TryAdd(requestType, null);
                        if (!suppress_throw)
                            throw new Exception("Error determining the bass class for the collection " +
                            collectionName + " from the type " + requestType.NiceTypeName() +
                            ". Collection declared by more than one Type (" + declaringClassType.NiceTypeName() +
                            ", " + tempDeclaringClassType.NiceTypeName() + ")");
                        declaringClassType = null;
                        return null;
                    }
                }
            }
            // Cache this result so we never have to go to all this work again!
            if (collectionName != null)
            {
                CollectionNameCache.TryAdd(requestType,
                    cachedEntry = new Tuple<Type, string>(declaringClassType, collectionName));
            }
            declaringClassType = cachedEntry?.Item1;
            return cachedEntry?.Item2;
        }
 
        public static string GetCollectionNameFromResourceHref(string href)
        {
            // Expect the collection to be in the second last segment of the reference URL.
            int guid_start = href.LastIndexOf('/', href.Length - 2);
            int collection_start = href.LastIndexOf('/', guid_start - 1) + 1;
            return href.Substring(collection_start, guid_start - collection_start);
        }
        #endregion Get Collection Name
        #endregion Public Utilities
 
        #region Internal Utilities / Helper Methods
        internal const string ERR_MISSING_ID =
            "The specified resource's 'id' property is missing. " +
            "Did you forget to POST this resource and store the result? For example:\n" +
            "var saved_resource = staged_resource.Post();";
 
        internal static string GetResourcePath(IAPIResource resource)
        {
            ValidateExistingResource(resource);
            return $"{resource.collection_name}/{resource.id}";
        }
 
        internal static string GetCollectionPath(IAPIResource resource)
        {
            if (resource == null)
                throw new ArgumentNullException(nameof(resource));
            return $"{resource.collection_name}/";
        }
 
        internal static RequestParameters AddRequestBodyParameters(
            IEnumerable<Parameter> requestParameters, object request_body)
        {
            return new RequestParameters(requestParameters)
                .AddParameter(JSON_CONTENT_TYPE, request_body, ParameterType.RequestBody);
        }
 
        internal static void ValidateExistingResource(IAPIResource resource)
        {
            if (resource == null)
                throw new ArgumentNullException(nameof(resource));
            ValidateResourceId(resource.id);
        }
 
        internal static void ValidateResourceId(string id)
        {
            if (String.IsNullOrEmpty(id))
                throw new ArgumentException(ERR_MISSING_ID);
            // TODO: Perhaps it is worthwhile to verify that the id is a valid GUID
        }
        #endregion Internal Utilities / Helper Methods
 
        #region Private Utilities / Helper Methods
        private static APIRequestException ServerErrorExceptionHelper(
            IRestResponse response = null, Exception inner = null,
            ServerError serverErr = null, string message = null)
        {
            if (message != null)
                return new APIRequestException(message, inner, response, serverErr);
            if (serverErr?.message != null)
            {
                message = (response != null ? "Server threw " + response.StatusCode
                    : "Server error") + ": " + serverErr.message.TrimEnd('.');
            }
            else if (response != null)
            {
                if (inner != null)
                {
                    message = "Server response content error: " + inner.Message.TrimEnd('.') +
                        ". Response Content: " + TryFormat(response.Content) +
                        "\n See inner exception and restResponse properties for details.";
                }
                else
                {
                    message = "Server response error. Response Status: " +
                        response.StatusCode + ", Content: " + TryFormat(response.Content) +
                        ". See restResponse property for details.";
                }
            }
            else if (inner != null)
            {
                message = "Exception encountered: " + inner.Message.TrimEnd('.') +
                    ". See inner exception for details.";
            }
            return new APIRequestException(message, inner, response, serverErr);
        }
 
        #region Debug Helper Methods
        private static void DebugRestRequest(IRestRequest request)
        {
            Debug.Write(request.PrettyPrint() + "\n");
        }
 
        private static void DebugRestResponse(IRestResponse response)
        {
            Debug.Write("\n" + response.PrettyPrint() + "\n");
        }
 
        #region Debug Printing Extension Methods
        public static string PrettyPrint(this IRestRequest request)
        {
            const int indent = 2;
            string pad = new string(' ', indent);
            StringBuilder result = new StringBuilder();
 
            result.AppendLine("Processing the following request: ");
            result.AppendLine($"{pad}Current Time:       {DateTime.UtcNow.ToString(DebugTimeFormat)}");
            result.AppendLine($"{pad}Request Method:     {request.Method}");
            result.AppendLine($"{pad}Request Resource:   " +
                (String.IsNullOrWhiteSpace(request.Resource) ? "(root)" : request.Resource));
            // Separate request parameters by type and write them out as a list.
            result.Append(String.Join("", request.Parameters.OrderByDescending(p => p.Type)
                .ThenBy(p => p.Name).Where(p => p.Type != ParameterType.RequestBody)
                .GroupBy(p => p.Type).Select(g => $"{pad}{g.Key} Params:".PadRight(20 + indent) +
                    String.Join("\n" + new string(' ', 20 + indent),
                    g.Select(px => $"{px.Name} = \"{px.Value}\"")) + "\n")));
            Parameter body = request.Parameters.FirstOrDefault(
                p => p.Type == ParameterType.RequestBody);
            if (body != null)
            {
                result.AppendLine(pad + "Request Body (" + body.Name + "): " +
                    TryFormat(body.Value, body.Name == JSON_CONTENT_TYPE, indent, true));
            }
            else
                result.Append(pad + "Request Body:       (null)");
            return result.ToString();
        }
 
        public static string PrettyPrint(this IRestResponse response)
        {
            const int indent = 2;
            string pad = new string(' ', indent);
            StringBuilder result = new StringBuilder();
 
            if (response.ResponseStatus == ResponseStatus.Completed)
                result.AppendLine("The following response was received:");
            else
                result.AppendLine("Error while receiving a response from the server:");
            result.AppendLine($"{pad}Current Time:       {DateTime.UtcNow.ToString(DebugTimeFormat)}");
            if (response.ResponseStatus != ResponseStatus.Completed)
            {
                result.AppendLine($"{pad}Response Status:    {response.ResponseStatus}");
                result.Append($"{pad}Response Error:     {response.ErrorMessage}");
                // None of the standard response logs are available if this is the case.
                return result.ToString();
            }
            // Avoid polluting logs with lots of RetryAfter logs by keeping them lean.
            if (response.StatusCode == HttpStatusCode.ServiceUnavailable)
            {
                Parameter retryHeader = response.Headers.FirstOrDefault(header =>
                    header.Name.Equals("Retry-After", StringComparison.OrdinalIgnoreCase));
                Parameter queuePosition = response.Headers.FirstOrDefault(header =>
                    header.Name.Equals("Queue-Position", StringComparison.OrdinalIgnoreCase));
                result.Append(pad + "Received '503 - Service Unavailable' with " +
                    (retryHeader == null ? "no Retry-After header" : $"Retry-After: {retryHeader.Value}") +
                    (queuePosition == null ? " and no Queue-Position header" : $" and Queue-Position: {queuePosition.Value}"));
                return result.ToString();
            }
            // Standard Response Logging
            result.AppendLine($"{pad}Response URI:       {response.ResponseUri}");
            result.AppendLine($"{pad}Response HTTP Code: " +
                $"({(int)response.StatusCode}) {response.StatusDescription}");
            result.AppendLine($"{pad}Response Headers:   " +
                String.Join("\n" + new string(' ', 20 + indent),
                    response.Headers.Select(p => $"{p.Name}: \"{p.Value}\"").OrderBy(s => s)));
            string contentType = String.IsNullOrWhiteSpace(response.ContentType) ?
                null : $" ({response.ContentType})";
            result.Append(pad + $"Response Body{contentType}: ".PadRight(20) +
                TryFormat(response.Content, contentType?.Contains("json") ?? false, indent, true));
            return result.ToString();
        }
 
        public static bool IsSuccessful(this IRestResponse response)
        {
            return response != null && response.ResponseStatus == ResponseStatus.Completed &&
                (((int)response.StatusCode) >= 200 && ((int)response.StatusCode) < 300);
        }
        #endregion Debug Printing Extension Methods
 
        private static string TryFormat(object content, bool tryJSON = false, int indent = 0,
            bool newLineIfMultiLine = false)
        {
            if (content == null) return "(null)";
            string retVal = content.ToString();
            if (String.IsNullOrWhiteSpace(retVal))
                return "(response content was either empty or got redirected to a user-defined stream)";
            if (retVal.Length >= 10000)
                return $"{retVal.Substring(0, 1000)}... " +
                    $"(response content is too long to display in full: {retVal.Length} characters)";
            // Often the server response is application/json, but with a value of "null", so avoid
            // that common exception by skipping this if that's the case.
            if (tryJSON && retVal != "null")
            {
                try
                {
                    JsonSerializerSettings s = new JsonSerializerSettings
                    {
                        DateParseHandling = DateParseHandling.None
                    };
                    retVal = JsonConvert.DeserializeObject(retVal, s).ToString();
                }
                // ReSharper disable once EmptyGeneralCatchClause (we don't care if it's not JSON)
                catch { }
            }
            // If this is a multi-line message, put it on it's own new line.
            if (newLineIfMultiLine && retVal.Contains("\n"))
                retVal = "\n" + retVal;
            // Add indenting if applicable.
            if (indent > 0)
                retVal = retVal.Replace("\n", "\n" + new string(' ', indent));
            return retVal;
        }
        #endregion Debug Helper Methods
        #endregion Private Utilities / Helper Methods
 
        #region Deprecated Methods
        [Obsolete("This method has been replaced with an overload that uses a PollingOptions object")]
        public static T PollUntilReady<T>(
            Func<T> functionThatMight503,
            double minPollInterval = 0d,
            double maxPollInterval = Double.MaxValue,
            double maxPollTotalTime = Double.MaxValue)
        {
            return PollUntilReady(functionThatMight503, new AnalyzeRe.PollingOptions(
                (int)minPollInterval * 1000, (int)maxPollInterval * 1000, (int)maxPollTotalTime * 1000));
        }
        #endregion Deprecated Methods
    }
}